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Who Should Read this Book? 



If you are a business professional who has a need for the 
decision-making tools available on the IBM Personal 
Computer as well as the principal support functions 
available on the IBM Professional Office System (PROFS), 
or if you want to know how to use the PROFS Personal 
Computer Connection (PROFS/PC 2 ), you should read this 
book. 



What this Book Will Tell You 



This book, Using the PROFS Personal Computer 
Connection, tells you how to install PROFS/PC 2 , what you 
need to know and do before you use the product, how to 
use PROFS/PC 2 , how to tailor the main menu to suit your 
needs, and how to respond to the messages you may get 
from time to time while you are using PROFS/PC 2 . 

You should read the "Introduction" to get an orientation 
to the whole system and to perform the tasks, especially 
the one-time tasks, necessary for you to use PROFS/PC 2 . 
The "Introduction" tells you how to: 

• Install PROFS/PC 2 . 

• Log on to the VM host where you're running PROFS. 
(A host system is the data processing system to which 



To the Reader vii 



The COBOL communications user mast write 
a message control program (JiCP) to handle 
messages transmitted between remote 
stations and the central computer before 
they can be processed by a COBOL program. 
General telecommunications access method 
(TCAM) information, as well as specific 
guidelines for creating an MCP, can be 
found in the publications: 



IBM OS/VS Telecommuni ca tions Access 
Method (TCAM) Concepts and, Facilitj.es , 
Order No. GC30-2042 

IBM QS/VS TCAM Programmer's Guide. Order 
No.~*GC30-2041 

The list of publications that follows 
contains the title and IBM form number of 
each IBM publication referred to in this 
publication: 

IBM V? COBOL for, OS/VS, Order No. 
GC2 6-3857 

VM/370 CMS User's Guide for COBOL, Order 
No. SC28-6469 

YM/370_SYStem Programmer's Guide, 
Order~No.~ GC20-1807 

OS/VS Linkage Editor and Loader, Order 
No. ~GC 26-38 1 3~ 



OS/VS 1_Data_ Managemen t fo£_gystett 
jgrograimers. Order No. GC26-3837 

Q§/Y§2_SYStem_Prggramming_LibrarYi. 2§t§ 

Management, Order No. GC26-3830 

Q§/Y§l_£22§§§_ M §thgd_Seryices , Order 
No." GC26-3840 

Q§/YS2_&S£SS§_M£tbQd_Sei:Yi.£es , Order 
No. GC26-3841 

OS/VS2 Independent Component: Access 
Method Services , Order No. GT26-3843 

OS/VS Tape Labels, Order No. GC26-3795 

OS/VS Virtual St orage Acce s s Method 
(VSAM) Programmer' s (guide. Order 
No. GC26-3838 

OS/VS Data Management Services Guide , 
Order No. GT00-0303 

OS/VS Data Management Macro 
Instructions , Order No. GT00-0305 

Q.§/V §„ jg ffssage ,. \ ibr ar y ,;„ ,I.inJsage_Editor 

and Loader Messages, Order 
No. GC38-1007 

IBM_0S_COBOL Interactive Debug Terminal- 
User's Guide and Reference, Order 
No. SC28-6465 



OS/VS 1, Planning_and„u se _guide, Order 
No. GC24-50 90 

0S/VS2 Pl anning Guide for Release 2 t 
Order No. ~GC28-0667 

QS/VS2 Release 2 Guide , Order 
No. GC28-0671 

OS/VS JCL Reference publications: 

OS/VS 1 JCL Reference, Order 
No. "*GC24-5099 

OS/VS 1 JCL Services, Order No. GC24- 
5100 

QS£y_S_2_JCL, Order No. GC 28-0 692 

OS/VS Checkpoint/Restart , Order 
No. GT00-0304 

O S/VS 1 storage Estimates, Order 
No. GC24-50 94 



OS/VS 1 Debugg in g_Gui. d e, Order 
No." GC24-5093 

QSZY§2_SYStem_Prggramming_LibrarY: 
Debugging_Handb.ggk , Order Nos. GC2 8-0708 
and GC28-0709 

OS/VS1 Utilities , Order No. GC26-3901 
OS/VS2 Utilities , Order No. GC26-3902 

0^_Sort/Merge_Programj|eris_GuJ l de, Order 
No. ~SC33-4007 

os/is_S2£.iZS^£ae-££2a£aaas£l§_Sai3. e .# 

Order No. SC33-4035 

OS gort /Merge Installation Reference 
MaterialT'order No. SC33-4004 

QS/VS sort/Merge I installation Reference 
Matirial, Order No. SC33-4034 



QS/VS 2. Storage Estimates, Order 
No. GC28-0604 

IBM OS,,, jT$G) COBOL Prompter Terminal 
User's Guide and Reference, Order 
No. SC28-6433 



OS/VS Data Management publications: 



Indus t ry Standards 



The OS/VS COBOL Compiler and Library, 
Release 2, is designed according to the 
specifications of the following industry 
standards {as understood and interpreted by 
IBM as of April, 1976): 

• The highest level of American National 
Standard COBOL, X3. 23- 1974 (excepting 
the Report Writer Hodule) . ANS COBOL 
X3. 23-1974 is compatible with and 
identical to International Organization 
for Standardization/Draft International 
Standard (ISO/DIS) 1989-COBOL. 



The highest level of American National 
Standard COBOL, X3. 23-1968 (including 
the Report writer module). ANS COBOL 
X3. 23- 1968 is compatible with and 
identical to ISO/E 1989-1972 
Programming Language-COBOL. 



Quick Reference to PROFS is a handy reference card to 
PROFS tasks. Use it as a quick memory jogger. (Order 
no. GX20-2408) 



IBM Personal Computer Publications 

For more information about the PC, you may want to 
refer to the following books: 

Disk Operating System, Version 2.0 or 2.1 tells you how 
to use DOS on the PC. (Order no. 6024001) 

IBM Personal Computer 3278/79 Emulation Control 
Program User's Guide explains how to use your IBM 
PC or IBM PC XT with the IBM PC 3278/79 Emulation 
Control Program, that is, the program that lets you 
emulate, or imitate, the functions of an IBM 3278 
typewriter keyboard and either the IBM 3278 Model 2 
Display Station or the IBM 3279 Model 2A Color 
Display Station. (Order no. 1502422) 

IBM 3270 Personal Computer Control Program User's 
Guide and Reference explains keys, functions, and 
procedures that are used to perform tasks on the IBM 
3270 Personal Computer. The IBM 3270 Personal 
Computer Control Program is designed to operate on 
the IBM 3270 Personal Computer machine 
configuration 5271 standard models 2, 4, and 6, when 
installed with IBM Personal Computer Disk Operating 
System, Version 2.0 or 2.1. (Order no. 1837434) 



x PROFS/PC 2 



The PROFS Personal Computer Connection (PROFS/PC 2 ) lets 
you work with selected PROFS tasks on the IBM Personal 
Computer. By using the 3278/79 adapter, the PC 3270, or the 
IBM Asynchronous Communications Adapter, you can transfer 
DOS files from the PC to the host system and you can transfer 
files from the host system to the PC. (Throughout this book, 
the PC 3270, both hardware and software, and a PC with the 
3278/79 adapter card and the 3278/79 Control Program are 
referred to as the "PC 327x.") Then you can work with these 
files either on the PC in a stand-alone mode or on the host 
system. You can move your incoming mail from PROFS to 
PROFS/PC 2 to open and respond to at a more convenient time 
or place. PROFS/PC 2 lets you look at, reply to, forward, erase, 
file, and resend notes. You can also create new notes. 
Actions you take during note processing can be transferred to 
the PROFS host system for processing or distribution to other 
PROFS users. If you have an optional printer attached to 
your Personal Computer, PROFS/PC 2 lets you print PROFS 
documents that you've transferred from the host system. 



What You Need to Use PROFS/PC 2 



Hardware 



You can perform both host-attached and stand-alone tasks by 
means of any one of the following products: 

• IBM Personal Computer or IBM Personal Computer XT 
with the following: 
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IHT-SOfiOCTION 



An OS/VS COBOL program can be processed 
by the IBM Operating System. The operating 
system consists of a number of pro cessin g 
programs and a con trol pro gram. 



The processing programs include the 
COBOL compiler, service programs, and any 
user-written programs. 

The control program supervises the 
execution or loading of the processing 
programs; controls the location, storage, 
and retrieval of data; and schedules jobs 
for continuous processing. 

A request to the operating system for 
facilities and scheduling of program 
execution is called a j ob. For example, a 
job could consist of compiling a program by 
utilizing the COBOL compiler. A job 
consists of one or more Job ste ps, each of 
which specifies execution of a program. 
The programmer can make requests to the 
operating system by using job control 
statements. 



Each job is headed by a JOB statement 
that identifies the job. Each job step is 
headed by an EXEC statement that describes 
the job step and calls for execution. 
Included in each job step are data 
definition (DD) statements, which describe 
data sets and request allocation of 
input/output devices. 



catalog, or in both (if they are not the 
same). The catalog itself is a data set 
residing on one or more mass storage 
devices. It is organized into indexes that 
relate each data set name to its location — 
the volume in which it resides and its 
position within the volume . Only the data 
set name and DISP parameter need be 
specified to identify a cataloged data set 
to the system. 

The catalog is originally created by a 
utility program. Once the catalog exists, 
any non-VSAH data set residing on either a 
mass storage device or a magnetic tape 
volume can be cataloged automatically by 
use of a catalog subparameter in a DD 
statement that refers to the data set. 
VSAM data sets are cataloged through Access 
Method Services. 



Several input/output devices grouped 
together and given a single name when the 
system is generated constitute a device 
£isLSs. Each device class can be referred 
to by a collective name. For example, one 
device class called SYSDA could consist of 
all the mass storage devices in the 
installation; another called SYSSQ could 
consist of all the mass storage devices and 
tape devices. 



EXECUTING A COBOL PROGRAM 



The data processed by 
processing program must 
data set. A data set is 
collection of one or mor 
logically related. Info 
set may or may not be re 
specific type, purpose, 
A data set may be, for e 
program, a library of su 
group of data records th 
processed by a COBOL pro 



execution of any 
be in the form of a 

a named, organized 
e records that are 
rraation in a data 
stricted to a 
or storage medium, 
xample, a source 
broutines, or a 
at is to be 
gram. 



Four basic operations are performed to 
execute a COBOL program: 

• Compilation 

* Linkage editing 

* Loading 

• Execution 



A data set resides in one or more 
volumes. A volume is a unit of external 
storage that is accessible to an 
input/output device. For example, a volume 
may be a reel of tape or it may be a mass 
storage device. 

To facilitate retrieval of a data set, 
the serial number of the volume upon which 
it resides can be entered, along with the 
data set name, in either the system catalog 
of data sets (SISCTLG) or in the VSAM 



COMPILATION 



Compilation is the process of 
translating a COBOL source program into a 
series of instructions comprehensible to 
the computer, i.e., machine language. In 
operating system terminology, the input 
(source program) to the compiler is called 
the source module. The output (compiled 
source program) from the compiler is called 
the object module. 
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LINKAGE EDITING 



0S/VS1 



The linkage editor is a service program 
that prepares object modules for execution, 
It can also be used to combine tiro or more 
separately compiled object modules into a 
format suitable for execution as a single 
program. The executable output of the 
linkage editor is called a load module , 
which must always be stored as a member of 
a partitioned data set- 



In addition to processing object 
modules, the linkage editor can combine 
previously edited load modules, with or 
without multiple object modules, to form 
one load module. 



During the process of linkage editing, 
external references between different 
modules are usually resolved. 



The 0S/VS1 control program divides 
storage into a number of discrete areas 
called partitions, job steps are directed 
to these partitions using a priority 
scheduling system; that is, jobs are not 
executed as encountered in the job stream 
but according to a priority code. The 
0S/VS1 control program provides for: 

• Priority scheduling of jobs using the 
class code 

• Concurrent scheduling and execution of 
up to 15 separately protected jobs 

• Heading one or more input streams 

For further information about the 
various optional features of the OS/VS 1 
control program, see the publication Q S/ VSI 
Rl&fiSi na_as.d_fise _G ui d e . 



LOADING 



The Loader is a service program that 
processes object and load modules, resolves 
any references to subprograms, and executes 
the loaded module. All these functions are 
performed in one step. The Loader cannot 
produce load modules for a program library. 

For detailed information on the Loader, 

see the publication QS/VS Linkage Editor 

and_ Loader, where a discussion of invoking 
the Loader can be found in "Using the 
Loader." 



EXECUTION 



0S/VS2 



The 0S/VS2 control prog 
storage into areas called 
0S/VS1, the OS/VS 2 control 
priority scheduling system 
concurrent execution of up 
In addition, the 0S/VS2 co 
provides for assignment of 
on a variable basis accord 
code. For further informa 
various optional features 
control program, see the p 
Planning and .Use Guide. 



ram divides 
regions. Like 
program uses a 
and provides for 
to 255 tasks, 
ntrol program 

storage regions 
ing to a region 
tion about the 
of the 0S/VS2 
ubli cation QS/VS2 



Actual execution is under supervision of 
the control program, which obtains a load 
module from a library, loads it into main 
storage, and initiates execution of the 
machine language instructions contained in 
the load module. 



OPERATING SYSTEM ENVIRONMENTS 



The IBM OS/VS COBOL Compiler and Library 
operates under control of Q5/VS1 or 0S/VS2 
{with or without TSO) , and under the CMS 
component of VH/370. OS/VS1 and 0S/VS2 can 
operate as independent systems or under 
control of VM/370. 



CONVERSATIONAL MONITOR SYSTEM 



The Conversational Monitor System (CMS) 
is a time-sharing system that depends upon 
the control program component of Virtual 
Machine Facility/370 (VM/3 70) for real 
computer management. CMS provides an 
extensive range of conversational 
programming capabilities at a remo 
terminal. The CMS command languag 
simplifies file and data handling 
the use of simple terminal command 
detailed description on the use of 
OS/VS COBOL Compiler and Library u 
see the publication IBM VH/370 CMS 
Guide_for_COBOL. This guide conta 
list of restrictions and limitatio 
using the OS/VS COBOL Compiler und 




Introduction 1 9 



JOB CONTROL PROCEDURES 



Communication between the COBOL 
programmer and the job scheduler is 
effected through nine job control 
statements (hereinafter called control 
statements) : 



1. Job Statement 

2. Execute Statement 

3. Data Definition statement 

4. PROC Statement 

5. PEND Statement 

6. Command Statement 

7. Delimiter Statement 

8. Null Statement 

9. Comment Statement 



Parameters coded in these control 
statements aid the job scheduler in 
regulating the execution of jobs and job 
steps, retrieving and disposing of data, 
allocating input/output resources, and 
communicating with the operator. 



The job stateme nt {he 
the JOB statement) marks 
job and, when jobs are s 
stream, marks the end of 
statements for the prece 
contain accounting infor 
an installation's accoun 
conditions for early ter 
job, regulate the displa 
messages, assign job pri 
specific class for job s 
specify the amount of ma 
allocated to the job, an 
later execution. 



reinaf ter called 

the beginning of a 
tacked in the input 

the control 
ding job. It may 
mation for use by 
ting routines, give 
mination of the 
y of job scheduler 
ority, request a 
cheduler messages, 
in storage to be 
d hold a job for 



The e xecute statement (or EXEC 
statement) marks the beginning of a job 
step and identifies the program to be 
executed or the cataloged procedure to be 
used. It may also provide job step 
accounting information, give conditions for 
bypassing the job step, pass control 
information to a processing program, assign 
a time limit for the execution of the job 
step and specify the amount of main storage 
to be allocated. 

The data defini tion statem e nt (or DD 
statement) describes a data set and 



reguests the allocation of input/output 
resources. The DD statement parameters 
identify the data set, give volume and unit 
information and disposition, and describe 
the labels and physical attributes of the 
data set. 



The P8QC statement appears as the first 
control statement in a cataloged procedure 
or an in-stream procedure and is used to 
assign default values to symbolic 
parameters defined in the procedure. 



The PM£_St4iSffi.©ai appears as the last 
control statement in an in-streara procedure 
and marks the end of the in-stream 
procedure. For further information about 
in-stream procedures, refer to the topic 
"Testing a Procedure as an In-Streara 
Procedure" in the chapter "Using the 
Cataloged Procedures." 

The comm§nd .statement is used by the 
operator to enter commands through the 
input stream. Commands can activate or 
deactivate system input and output units, 
reguest printouts and displays, and perform 
a number of other operator functions. 



The delimiter sta t 
statemen t are markers 
The delimiter stateme 
is included in the in 
separate the data fro 
statements. The null 
to mark the end of th 
for the entire job (p 
statements from being 
job). 
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The comment statemen 
before or after any con 
can contain any intorma 
by the person who codes 
statements. Comments c 
columns 4 through 80. 
be continued onto anoth 
the comment statement a 
output listing, it can 
appearance of asterisks 
through 3. 



t can be inserted 
trol statement and 
tion deemed helpful 

the control 
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The comment cannot 
er statement. If 
ppears on a system 
be identified by the 

in columns 1 



The sequence of control statements 
required to specify a job is called a job 
control procedure . 

For example, the job control procedure 
shown in Figure 1 could be placed in the 
input stream to compile a COBOL source 
module. 
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I//J0B1 
\ //STEP 1 
I//SYSUT1 
| //SYSUT 2 
J //SYSUT 3 
I//SYSUT4 
I //SYS PRINT 
I//SYSPUNCH 
I//SYSIN 



JOB 

EXEC 

DD 

DD 

DD 

DD 

DD 

DD 

DD 



I 

I/* 
i 



(source deck) 



PGM=IKFCBL00, PARM=DECK 

DSNAM£=&&UT1,UNIT=SYSDA,SPACE= (TRK, (40) ) 
DSNAME=S&UT2,UNIT=SYSSQ,SPACE=(TRK, (40) ) 
DSNAME=S&UT3,UN.IT=SYSSQ,SPACE=(TRK# (40) ) 
DSNAME=&&UT4,UNIT=SYSSQ,SPACE=(TRK, (40) ) 
SYSOUT=A 
SYSOUT=B 
* 



Figure 1. Job Control Procedure 



In the illustration, JOB1 is the name of 
the job. The JOB statement indicates the 
beginning of a job. 



STEP1 is the name of the single job step 
in the job. The EXEC statement specifies 
that the IBM OS/VS COBOL Compiler 
(IKFCBL00) is to execute the job. The 
statement also specifies that a card deck 
of the object module is to be produced 
(PARM=DECK) . 



The SYSUT1, SYS0T2, SYSUT 
SYS0T5 (if the SYMDMP or TES 
specified in the PARM parame 
card) , and SYS0T6 (if the LV 
specified in the PARM parame 
card) DD statements define u 
sets, used by the compiler to 
source module. The names of 
defined by SYSUT1, SYSUT2, S 
SYSUT5 and SYSUT6 are &&UT1, 
&&0T4, &&UT5 and S&UT6, resp 
SYSUT1 must be on a mass sto 
(UNIT=SYSDA) . The system wi 
tracks of space to SYSUT 1 
[SPACE=(TRK, (40)) ]. The oth 
data sets are assigned eithe 
available tape, in which cas 
parameter is ignored, or to 
unit (UNIT=SYSSQ). 
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The SYSPRINT DD statement defines the 
data set that is to be printed. SYSODT=A 
is the standard designation for data sets 
whose destination is the system output 
device, usually indicating that the data 
set is to be listed on a printer. 

The SYSPUNCH DD statement defines the 
data set that is to be punched. By 
convention, SYSOtJT=B designates a card 
punch. 

The SYSIN DD statement defines the data 
set (in this case, the source module) that 
is to be used as input to the job step. 
The asterisk (*) indicates that the input 
data set follows in the input stream. 



The delimiter (/*) statement separates 
data from subsequent control statements in 
the input stream. 

Output from this job step includes any 
diagnostic messages associated with the 
compilation. They are printed in the data 
set specified by SYSPRINT. 

Noie: SYSDA, SYSSQ, A, and B are 
IBM-specified device class names. If they 
are to be used, they must be incorporated 
at system generation time. 

To avoid rewriting these statements, and 
the possibility of error, the programmer 
may place frequently used procedures on a 
system library called the procedure 
library. A procedure contained in the 
procedure library is called a cataloge d 
pr oced ure. A cataloged procedure can be 
called for execution by placing in the 
input stream a simple procedure that may 
require only the JOB and EXEC statements. 

If slightly modified, the procedure in 
the previous example can be cataloged, 
i.e., placed in the procedure library. For 
example, if it were cataloged and given the 
name CATPROC, it could be called for 
execution by placing the statements shown 
in Figure 2 in the input stream. 



r 




1 


I //JOB 2 JOB 




i 


I//STEPA EXEC 


PROC=CATPROC 


J 


J//STEP1. SYSIN DD 


* 


1 


J (source deck) 




i 


I/* 




\ 


i 




j 



Figure 2. Using a Cataloged Procedure 



In Figure 2, J0B2 is the name of the job. 
ST1PA is the name of the single job step. 
The EXEC statement calls the cataloged 
procedure containing STEP1 to execute the 
job step (PROC=CATPROC) . 



Job Control Procedures 21 



A procedure can be tested before it is 
placed in the procedure library by 
converting it into an in-stream procedur e. 
An in-strean procedure can be executed any 
number of times during a job. For further 
information about in-stream procedures, 
refer to the topic "Testing a Procedure as 
an In-Stream Procedure" in "Using the 
Cataloged Procedures." 
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The section "Control Statements," below, 
shows the format and use of the parameters 
and subparameters that can be specified for 
each job control statement. Some 
parameters of the statements are described 
only briefly. For further information, see 
the publication QS/YS JC L Referenc e. The 
syntactic format descriptions in this 
chapter can be used as a reference for the 
exact format and for the use of each 
parameter. 



CONT ROL ST ATEMENTS 



The COBOL programmer uses the control 
statements shown in Figure 3 to compile, 
linkage edit, and execute programs. 



JOB MANAGEMENT 



Control statements are processed by a 
group of operating system routines known 
collectively as job management. These job 
management routines interpret control 
statements and commands, control the flow 
of jobs, and issue messages to both the 
operator and the programmer. Job 
management comprises two major components: 
a job scheduler and a master scheduler. 

T^ e lob scheduler is a set of routines 
that reads input streams, analyzes control 
statements, allocates input/output 
resources, issues diagnostic messages to 
the programmer, and schedules job flow 
through the system. 



J State men 
i 



— r 

t| 

-+ 



Function 



I JOB | Indicates the beginning of 

| ) new job and describes tha 

I I job. 
I h 



IEXEC | Indicates a job step and 
1 J describes that job step; 
I \ indicates the load module 
I J cataloged procedure to be 
| | executed. 
1 H 



1 

I 

I 

or | 



|DD 

I 

J 



I Describes data sets, and 
J controls device and volui 
f assignment. 
-I 



1 

I 

j 

I 
ie 1 

J 



| delimiter J Separates data sets in the 
J input stream from control 
statements; it may follow 
each data set that appear 
the input stream, e.g., a 
a COBOL source module pun 
deck. 
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1 J and notes written by the J 

I J programmer; it may appear J 

J 1 anywhere in the job stream J 

| \ after the JOB statement } 

i \ ^except within data or } 

1 | source). J 

« j i 



Figure 3. control Statements 



The master scheduler is a set of 
routines that accepts operator commands and 
acts as the operator's agent within the 
system. It relays system messages to the 
operator, performs system functions at his 
request, and responds to his inguiries 
regarding the status of a job or of the 
system. The master scheduler also relays 
all communication between a processing 
program and the operator. 



PREPARING CONTROL STATEMENTS 



Except for the comment statement, 
control statements are identified by the 
initial characters // or /* in card columns 
1 and 2. The comment statement is 
identified by the initial characters //* in 
columns 1 through 3. Control statements 
may contain four fields: name, operation, 
operand, and comment, as shown in Figure H. 
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Columns 



Fields 



i a — i 1 

Statement J 1J2|3 J 4 

j — +_| — i : . 

Job | /l/Jnarae JOB operand 1 comments* 

Execute J /J /| name* EXEC operand comments* 

Data Definition! /l/|name* DD operand comments* 

Procedure | /|/|name* PROC operand comments* 

Command J /1/| operation (command) operand 

Delimiter I /I* I comments* 

Hull | /|/| 

Comment 1 /I/ J* comments 

Pend | /|/fnarae* PEND 



comments* 



I *optional. 
i 



Figure 4. General Format of Control Statements 



Name Field 



Op erand Field 



The name contains from one through eight 
alphanumeric characters, the first of which 
must be alphabetic. The name begins in 
card column 3. It is followed by one or 
more blanks. The name is used, as follows: 



• To identify the control statement to 
the operating system 



To enable other control statements in 
the job to refer to information 
contained in the named statement 



• To relate DD statements to files named 
in a COBOL source program 



Operation Field 



The operation field is preceded and 
followed by one or more blanks. It may 
contain one of the following operation 
codes; 

JOB 
EXEC 
DD 
PROC 

PEND 



If the statement is a delimiter statement, 
there is no operation field and comments 
may start after one blank. 



The operand field is preceded and 
followed by one or more blanks and may 
continue through column 71 and onto one or 
more continuation cards. It contains the 
parameters or subparameters that give 
required and optional information to the 
operating system. Parameters and 
subparameters are separated by commas. A 
blank in the operand field causes the 
system to treat the remaining data on the 
card as a comment. There are two types of 
parameters: positional and keyword 
(Figures 5, 6, and 9). 

Positional Par a meter s: Positional 
parameters are the first parameters in the 
operand field, and they must appear in the 
specified sequence. If a positional 
parameter is omitted and other positional 
parameters follow, the omission must be 
indicated by a comma. If other positional 
parameters do not follow, no comma is 
needed. 



Keyword Parameters : A 
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Subparameters are either positional or 
keyword. Positional and keyword 
subparameters for job control statements 
are shown in Figures 5, 6, and 9. 
Positional subparameters appear first in 
the parameter and must be in the specified 
sequence. If a positional subparameter is 
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omitted and other positional sub parameters 
follow, a comma must indicate the omission. 



Comments Field 



1 through 71 of cards or card images. If 
the total length of a statement exceeds 71 
columns, or if a parameter is to be placed 
on separate cards, the operating system 
continuation conventions must be used. To 
continue an operand field: 



Optional comments must be separated from 
the last parameter (or the /* in a 
delimiter statement) by one or more blanks 
and may appear in the remaining columns up 
to and including column 71. An optional 
comment may be continued onto one or more 
continuation cards- Comments can contain 
blanks. 

Note: comments in the optional comments 
field follow different procedures from 
those on the comment statement. 



3. 



Interrupt the field at the end of a 
complete parameter or subpara meter, 
including the comma that follows it, 
at or before column 7 1. 



Include any commraents desired by 
following the interrupted field with 
at least one blank. 



Optionally, code any nonblank 
character in column 72. 



CONVENTIONS FOB CHARACTER DELIMITERS 



Commas, parentheses, and blanks are 
interpreted as character delimiters. If 
they are not intended by the programmer to 
be used as delimiters, the fields in which 
they appear must be enclosed in single 
guotation marks, indicating that the 
enclosed information is to be treated as a 
single field. When an apostrophe {or a 
single quotation mark, since the same 
character is used for either) is to be 
contained within such a field, it must be 
shown as two consecutive single quotatio n 
marks (5-8 punch), not as a double 
guotation mark (7-8 punch) . For example, 

Wm. O* Connor 

should be shown as 

* Wm. 0« 'Connor* 



This convention applies to three fields: 
programmer's name in the JOB statement, 
information in the PAHM parameter of the 
EXEC statement, and accounting information 
in the JOB and EXEC statements. 



4. code the identifying characters // in 
columns 1 and 2 of the following card 
or card image. 



5. continue the interrupted operand 

beginning in any column from 4 through 
16. 



Comments other than those on a comment 
statement can be continued onto additional 
cards after the operand has been completed. 
To continue a comments field: 



1. Interrupt the qomment at a convenient 
place. 



2. Code a nonblank character in column 
72. 

3. Code the identifying characters // in 
columns 1 and 2 of the following card 
or card image. 

4. Continue the comments field beginning 
in any column after column 3. 



BOLES FOE CONTINUING CONTBOI STATEHENTS 



Except for the comment statement, 
control statements are contained in columns 



Any control statements in the input 
stream that the job scheduler considers to 
contain only continued comments will print 
on a system output listing with a //* in 
columns 1 through 3. Comments written on a 
comment statement cannot be continued. 
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NOTATION FOR DESCRIBING JOB CONTROL 
STATEMENTS 



The notation used in this publication to 
define the syntax of job control statements 
is as follows: 

1. The set of symbols below define 

control statements, but they are never 
written in an actual statement. 



Name 
hyphen 



Sym b ol 



"or" symbol J 
braces { } 



brackets 



[ 1 



ellipsis 



superscript * 2 3 



Purpose 
Joins lower-case 
letters, words, and 
symbols to form a 
single variable 

Indicates alternatives 

Indicate that the 
enclosed is a group of 
related items, only 
one of which is 
required 

Indicate that the 
enclosed are optional 
items. Brackets are 
also used with 
alternatives to 
indicate that a 
default is assumed if 
no alternative is 
listed 

Indicates that the 
preceding item or 
group of items can be 
repeated 

Indicates a footnote 
reference 



Stacked items, enclosed in either 
brackets or braces, represent 
alternative items. No more than one 
of the stacked items can be written by 
the programmer. 

Upper-case letters and words, numbers, 
and the set of symbols listed below 
are written in an actual control 
statement exactly as shown in the 
statement definition. (Any exceptions 
to this rule are noted in the 
definition of a control statement.) 



Name 

single quotation mark 

asterisk 

comma 

equal sign 

parentheses 

period 

slash 



Symbol 
t 

* 

i ) 
/ 



An underscore indicates a default 
option. If an underscored alternative 
is selected, it need not be written in 
the actual statement. 



N ot e: Many of these defaults can be 
changed at system generation time. 

5. Lower-case letters, words, and symbols 
appearing in a control statement 
definition represent variables for 
which specific information is 
substituted in the actual statement. 

6. Blanks are used in Figures 5, 6, 8, 
and 9 to improve the readability of 
control statement definitions. In 
actual statements, blanks would be 
interpreted as delimiters. 



JOB STATEMENT 



The JOB statement is the first statement 
in the sequence of control statements that 
describe a job. The JOB statement can 
contain the following information: 

1. Name of the job. 

2. Accounting information relative to the 
job. 

3. Programmers name. 

4. Indication of whether or not the job 
control statements are to be printed 
on the system output listing. 

5. Conditions for terminating the 
execution of the job. 

6. Job priority assignment, job scheduler 
message class, and real or virtual 
region size. 

Figure 5 is a general format of the JOB 
statement. 



iobnameJL 



The jobname identifies the job to the 
job scheduler. It must satisfy the 
positional, length, and content 
requirements for a name field. No two jobs 
being handled by a priority scheduler 
should have the same jobname. 
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t r 

J Operation 

H — 



I Name 



Operand 



I ! 

I I 

I I 

J//jobname J JOB 



1 I 
J 
I 



I 



Positional Parameters 
[ ([account-number J [, accounting- information ]) * 2 3] 
[ , programmer-name]* * 

Ke ywo rd Parameters 

[MSGLEVEL={x,y) ]* 
[TIME= (minutes, seconds) ] 
[ CIASS= jobclass] 

[COND=((code, operator) [, (code, operator) ]. ,. 7 ) 8 ] 
[PRTI=job priority] 
[ H SGCL ASS=classname ] 
[REGION=valueK] 
[RD= request] 
* 

[RESTART=(f stepname ) [ ,checkid ]) ] 

\ stepname. procstepname/ 
[NOTIFi=user id]» 

r /HOLD) 

[ TTPRUN= \SCANJ 

f (11B1\ 1 

[ ADDRSPC= j REAL I J 



r 



| »If the information specified (account-number and/or accounting- information) contains 

J blanks, parentheses, or equal signs, the information must be delimited by single 

I quotation marks instead of parentheses. 

j 2 If only account-number is specified, the delimiting parentheses may be omitted. 

J 3 The maximum number of characters allowed between the delimiting quotation marks is 

1 142. 

} *If programmer-name contains any special characters other than the period, it must be 

J enclosed within single quotation marks. 

j SThe maximum number of characters allowed for programmer-name is 20. 

I *x = 0, 1, or 2 is the JCL message. 

1 y = or 1 is the allocation message level. 

J Note that the value 1 may be used in place of (1,1). 

J 7 The maximum number of repetitions allowed is 7. 

I 8 If only one test is specified, the outer pair of parentheses may be omitted. 

\ *For TSO only. 

I » os CAN is for OS/VS1 only. 



Figure 5. JOB Statement 



JOB PARAMETERS 



j , 

I (acct#, additional accounting information) 1 

I : . i 



Supplying Job Accounting Information 



For job accounting purposes, the JOB 
statement can be used to supply information 
to an installation's accounting procedures. 
To supply job accounting information, code 
the positional parameter first in the 
operand field. 



Replace the term "acct#" with the account 
number to which the job is charged; replace 
the term "additional accounting 
information" with other items required by 
an installation's accounting routines. The 
requirement can be established with a 
cataloged procedure for the input reader. 
Otherwise, the account number. is considered 
optional. 
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Notes; 

• subparameters of additional accounting 
information must be separated by 
commas. 

• The number of characters in the account 
number and additional accounting 
information must not exceed a total of 
142. 

• If the list contains only an account 
number, the programmer need not code 
the parentheses. 

• If the list does not contain an account 
number, the programmer must indicate 
its absence by coding a comma preceding 
the additional accounting information. 

• If the account number or any 
subparameter of additional accounting 
information contains any special 
character {except hyphens) , the 
programmer must enclose the number or 
subparameter in apostrophes {5-8 
punch) . The apostrophes are not passed 
as part of the information. 



Identif yin g, the Pro g ra mm er 



The person responsibl 
his name or identificati 
statement, following the 
information. This posit 
also passed to an instal 
As a system generation o 
programmer's name can be 
required parameter. The 
also be established with 
procedure for the input 
this parameter is consid 

Notes: 



e for a job codes 
on in the JOB 

job accounting 
ional parameter is 
lation's routines, 
ption, the 

established as a 

reguirement can 

a cataloged 
reader. Otherwise, 
ered optional. 



• The number of characters in the name 
cannot exceed 20. 

• If the name contains spacial characters 
other than periods, it must be enclosed 
in apostrophes. If the special 
characters include apostrophes, each 
must be shown as two consecutive 
apostrophes, e.g., ' T. 0* * NEI1L*. 

• If the job accounting information is 
not coded, the programmer must indicate 
its absence by coding a comma preceding 
the programmer-name. 

• If neither job accounting information 
nor programmer-name is present, the 
programmer need not code commas to 
indicate their absence. 



Disp laying All Control Statements^ 
Alloca tion, and Terminatio n .Messages 



The HSGLEVEL parameter indicates whether 
or not the programmer wants control 
statements and/or allocation and 
termination messages to appear in his 
output listing. To receive this output, 
code the keyword parameter in the operand 
field of the JOB statement. 



MSGLEVEL={X,y) 



The letter "x" represent 
language message code and c 
the value 0, 1 , or 2. When 
specified, only the JOB sta 
incorrect control statement 
associated diagnostic messa 
displayed. When x = 1 is s 
statements, cataloged proce 
and symbolic substitution o 
displayed. When x = 2 is s 
input statements are displa 



s a job control 
an be assigned 

x = is 
tement, 
s, and 
ges are 

pecified, input 
dure statements, 
f parameters are 
pecified, only 
yed. 



The letter "y 
message code and 
or 1 . When y 
allocation, term 
messages are dis 
occurs during pr 
If an ABEND occu 
are displayed. 
all allocation, 
messages are dis 



" represents an allocation 
can be assigned the value 
= is specified, no 
ination, or recovery 
played, unless an ABEND 
oblem program execution, 
rs, termination messages 
When y = 1 is specified, 
termination, and recovery 
played. 



Notes: 



If the value 1 is selected for both 
codes, the value may be specified once 
without the parentheses; i.e., 
MSGLEVEL=1 is the same as 
M5GLEVEL={1, 1). 



The default values are taken froi 
reader procedure. 



the 



If an error occurs on a control 
statement that is continued onto one or 
more cards, only one of the 
continuation cards is printed with the 
diagnostic messages. 



Specif ying cond it ions for Job Termination 
1C0NDL 



To eliminate unnecessary use of 
computing time, the programmer might want 
to base the continuation of a job on the 
successful completion of one or more of 
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its job steps. At the completion of each 
job step, the processing program passes a 
number to the job scheduler as a return 
code. The COND parameter provides the 
means to test each return code as many as 
eight times. If any one of the tests is 
satisfied, subsequent steps are bypassed 
and the job is terminated. 



To specify conditions for job 
termination, code the keyword parameter in 
the operand field of the JOB statement. 

» ■■ T 

I CON D= {(code, operator) ,.., (code, operator) ) J 
i 1 



See the COND parameter on the EXEC 
statement for a discussion of the operator 
values and the codes issued by the compiler 
and linkage editor at the end of a job 
step. 



Note: 

• The subparameters EVEN and ONLY cannot 
be specified as part of the COND 
parameter on the JOB statement. 



Req uesting Restart for a Job (RD ) 



The restart facilities are used in order 
to minimize the time lost in reprocessing a 
job that abnormally terminates. These 
facilities permit execution of jobs that 
abnormally terminate to be automatically 
restarted. 

Execution of a job can be automatically 
restarted at the beginning of the job step 
that abnormally terminated (step restart) 
or within the step (checkpoint restart). 
In order for checkpoint restart to occur, 
the CHKPT macro instruction must have been 
executed in the processing program prior to 
abnormal termination. The CHKPT macro 
instruction is activated by the COBOL 
source language RERUN clause. The SD 
parameter specifies that step restart can 
occur or that the action of the CHKPT macro 
instruction is to be suppressed. 

To request that step restart be 
permitted or to reguest that the action of 
the RERUN clause be suppressed, code the 
Ice y word parameter in the operand field of 
the JOB statement. 



RD= re quest 



Replace the word "request" with; 

R — to permit automatic step 
restart 

NC — to suppress the action of the 

CHKPT macro instruction and not 
to permit automatic restart or 
deferred restart 

NR — to request that the CHKPT macro 
instruction be allowed to 
establish a checkpoint, but not 
to permit automatic restart. 
Deferred restart is permitted 
through specification of 
RESTART on the resubmitted job. 

RNC — to permit step restart and to 
suppress the action of the 
CHKPT macro instruction 

Each of these requests is described in 
greater detail in the following paragraphs. 

RD=R : If the processing programs used by 
the job do not include any CHKPT macro 
instructions, 8D=R allows execution to be 
resumed at the beginning of the step that 
causes abnormal termination. If any of the 
programs do include one or more CHKPT macro 
instructions, step restart can occur if a 
step abnormally terminates before execution 
of a CHKPT macro instruction; thereafter, 
checkpoint restart can occur. 

BD=NC or RD-RNC; RD=NC or RD=RNC should be 
specified to suppress the action of all 
CHKPT macro instructions included in the 
programs, when RD=NC is specified, neither 
step restart nor checkpoint restart can 
occur. When RD=RNC is specified, step 
restart can occur- 

BD=NR: RD=NR permits a CHKPT macro 
instruction to establish a checkpoint, but 
does not permit automatic restart. 
Instead, at a later time, the job can be 
resubmitted and execution can begin at a 
specific checkpoint. (Resubmitting a job 
for restart is discussed later.) 

Before automatic step restart occurs, 
all data sets in the restart step with a 
status of OLD or MOD, and all data sets 
being passed to steps following the restart 
step, are kept. All data sets in the 
restart step with a status of NEW are 
deleted. Before automatic checkpoint 
restart occurs, all data sets currently in 
use by the job are kept. 

If the RD parameter is omitted and no 
checkpoints are taken, automatic restart 
cannot occur. If the RD parameter is 
omitted but one or more checkpoints are 
taken, automatic checkpoint restart can 
occur. 
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Notes: 

• For 0S/VS1 restart can occur only if 
MSGLEVEL=1 is coded on the JOB 
statement. 

• If step restart is requested, each step 
must be assigned a unique step name. 

• If no RERUN clause is specified in the 
user's program, no checkpoints are 
written regardless of the disposition 
of the RD parameter. 

Reference: 



Replace the word stepname with the name of 
the step in which execution is to be 
restarted. Replace the term "checkid" with 
the 1- to 16-character name that identifies 
the checkpoint within the step. 



If execution is to be restarted at a 
checkpoint, the resubmitted job must 
include an additional DD statement. This 
DD statement defines the checkpoint data 
set and has the ddname SYSCHK. Do not 
include a SYSCHK DD statement if step 
restart is to be perfori 



For detailed information on the 
checkpoint/restart facilities, see the 
publication OS/VS Checkpoint/Restart . 



If the RESTART parameter is not 
specified on the JOB statement of the 
resubmitted job, execution is repeated. 



Notes: 



Resubmit ting a Jo b for R estart ( RESTART) 



The restart facilities can be used if 
the job is abnormally terminated and the 
programmer wants to resubmit the job for 
execution. These facilities reduce the 
time required to execute the job since 
execution of the job is resumed, not 
repeated. 

Execution of a resubmitted job can be 
restarted at the beginning of a step (step 
restart) or within a step (checkpoint 
restart) . In order for checkpoint restart 
to occur, a program must previously have 
had a checkpoint record written. The 
RESTART parameter specifies where execution 
is to be restarted. 

If execution is to be restarted at a 
particular job step, code the keyword 
parameter in the operand field of the JOB 
statement before resubmitting the job. 



RESTART=stepname 



Replace the word "stepname" with the name 
of the step at which execution is to be 
restarted. Replace stepname with an 
asterisk (*) if execution is to be 
restarted at the first job step. 

If execution is to be restarted at a 
particular checkpoint within a particular 
job step, code the keyword parameter in the^ 
operand field of the JOB statement before 
resubmitting the job. 



If execution is to be restarted at or 
within a cataloged procedure step, give 
both the name of the step that invokes 
the procedure and the procedure step 
name, as below. 



BESTART=stepname. procstepname 



* If step restart is performed, 

generation data sets that were created 
and cataloged in steps preceding the 
restarted step must not be referred to 
in the restart step or in steps 
following the restart step by means of 
the same relative generation numbers 
that were used to create them. For 
example, a generation data set assigned 
a generation number of +1, would be 
referred to as in the restart step or 
steps following the restart step. 



Backward references cannot be made to 
steps that precede the restart step 
using the following keyword parameters: 
PGM, COND, SUBALLOC, and V0LU2?E=REF, 
unless in the last case the referenced 
statement includes V0LU8E=SER= (serf) . 



Refer ence: 

• For detailed information on the 

checkpoint/restart facilities, see the 
pu bl icat ion QS/VS Checkpoint/Restart. 



SESTART= {stepname, checkid) 
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PRI08ITY SCHEDULING JOB PA5AHETE8S 



Setting Job Time Limit s £T_IJgEJL 



To assign a limit to the computing time 
used by a job, code the keyword parameter 
in the operand field. 



TIME= (minutes, seconds) 



to make the job part of the group of 
jobs to be time-sliced. Tiae- slicing 
permits the processing of tasks of 
equal priority so that each is executed 
for its specified period of time. At 
system generation, a group of 
contiguous partitions are selected to 
be used for time-slicing, and each 
partition is assigned at least one job 
class. If the job is to foe 
time-sliced, specify a class that was 
assigned only to the partitions 
selected for time-slicing. 



Such an assignment is useful in a 
multiprogramming environment where more 
than one job has access to the computing 
system. The time is coded in minutes and 
seconds to represent the maximum time for 
execution of a job. 

Notes; 

* The number of minutes cannot exceed 
1439 and the number of seconds cannot 
exceed 59. If the job is not completed 
in this time it is terminated. 

* If the job requires use of the system 
for more than 24 hours {1439 minutes) 
specify TIME=144 0. This number 
suppresses job timing. 

* If the time limit is given in minutes 
only, the parentheses need not be 
coded; e.g., TIME=5. 

* If the time limit is given in seconds, 
the comma must be coded to indicate the 
absence of minutes; e.g., TIHE={,45). 

* If the TIME parameter is omitted, the 
default job time is assumed. 



Assigning a Job Clas s (CLASS ) 



To assign a job class to a job, code the 
keyword parameter in the operand field of 
the JOB statement. 



CLASS= jobclass 



Assigning Job Priorit y (PRTY1 



To assign a priority other than the 
default job priority (as established in the 
input reader procedure) , code the keyword 
parameter in the operand field of the JOB 
statement. 



PBTY=nn 



Replace the letters "nn" with a decimal 
number from through 13 (the highest 
priority number is 13) . 

If an installation provides time-slicing 
facilities in a system with 0S/VS2, the 
PRTY parameter can be used to make the job 
part of a group of jobs to be time-sliced. 
At system generation, the priority of the 
time-sliced group is selected. If the job 
priority number specified corresponds with 
the priority number selected for 
time-slicing, then the job will be 
time-sliced. 

If the PSTY parameter is omitted, the 
default job priority is assigned to the 
job. 

Note: Whenever possible, avoid using 
priority 13. This is used by the system to 
expedite processing of jobs in which 
certain errors were diagnosed. It is also 
intended for other special uses by future 
features of systems with priority 
schedulers. 



The meaning and use of the term "jobclass" 
is pre-defined by each installation. If 
the CLASS parameter is omitted, the default 
job class of A is assigned to the job. 

Ng_te: 

* If an installation provides 

time-slicing facilities in an 0S/VS1 
system, the CLASS parameter can be used 



Heques ting a M essage Class |MSGCLASS) 



With the quantity and diversity of data 
in the output stream, an installation may 
want to separate different types of output 
data into different classes. Each class is 
directed to an output writer associated 
with a specific output unit. The MSGCLASS 
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parameter allows routing of all messages 
issued by the job scheduler to an output 
class other than the normal message 
class, A. 

To choose such a class, code the keyword 
parameter in the operand field of the JOB 
statement. 



1 — — 

1 


MSGCLASS=X 


J 


I ._ . 




j 



Replace the letter "x" with an alphabetic 
{A-Z) or numeric (0-9) character. An 
output writer, which is assigned to process 
this class, will transfer this data to a 
specific device. 

If the MSGCLASS parameter is omitted, 
job scheduler messages are routed to the 
standard output class, A. 

Ref ere nce: 

• For a more detailed discussion of 
output classes, see the appropriate 
planning and Dse Guide. 



Spec if yinq M ai J!_ Stor a ge Requ iremen ts for a 
Job (REGION) 

For jobs that require an unusual amount 
of main storage, the JOB statement provides 
the REGION parameter. The REGION parameter 
specifies the maximum amount of main 
storage to be allocated to the job. This 
amount must include the size of those 
components required by the user's program 
that are not resident in main storage. 

The REGION parameter is used in 
conjunction with the ADDRSPC parameter to 
determine the total amount of main storage 
available to a program and to either allow 
or disallow paging. 

Note: The REGION parameter has different 
leanings for OS/VS1 and 0S/?S2. see the 
publication OS/VS JCL services for detailed 
information. 



If the REGION parameter is omitted or if 
a region size smaller than the default 
region size is requested, it is assumed 
that the default value is that established 
by the input reader procedure. 

The REGION parameter can be used with 
either the VIST or REAL options of the 
ADDRSPC parameter. 

Notes : 

• Region sizes for each job step can be 
coded by specifying the REGION 
parameter in the EXEC statement for 
each job step. However, if a REGION 
parameter is present in the JOB 
statement, it overrides REGION 
parameters in EXEC statements. 



• For information on storage requirements 
to be considered when specifying a 
region size, see the appropriate 
Storage Estimates publication. 



Hpldi^g a Job for. Later Execution 

To temporarily prevent a job from being 
selected for processing, code the keyword 
parameter in the operand field of the JOB 
statement. 



™=nr 



The job is then held until a RELEASE 
command is issued by the operator. This 
specification is particularly useful when 
one job must be run after another job has 
terminated. 

HOLD specifies that the job is to be 
held until the operator issues a RELEASE 
command. SCAN (for OS/VS 1 only) specifies 
that the JCL for a job is to be scanned for 
syntax errors but that the job is not to be 
executed. If SCAN is specified for OS/VS2, 
a JCL error will occur. 



To specify a region size, code the 
keyword parameter in the operand field of 
the JOB statement. 



Specifying Address Space {ADDRSPC) 



REGION=<nnnnnxK[ ,nnnnnyK]) 



To request the maximum amount of main 
storage reguired by the job, the term 
"nnnnnx" should be replaced with the number 
of 1024-byte areas allocated to the job, 
e.g., REGION=52K. This number can range 
from 1 to 5 digits but cannot exceed 16383. 



To take advantage of the storage 
facilities offered by OS/VS1 and OS/VS2, 
always specify ADDRSPC = VIRT or omit the 
parameter. 



ADDRSPC= \REALJ 
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Note that the compiler and its object code, 
including library subroutines, can run 
VIRTUAL, and should be run that way unless 
a non-COBOL program in the partition 
requires the 8EAL option. 



positional, length, and content 
requirements for a name field. The 
programmer must specify a stepname if later 
control statements refer to the step. 



EXEC STATEMENT 



POSITIONAL PASAMETEBS 



The EXEC statement defines a job step 
and calls for its execution. It contains 
the following information: 

1. The name of a load module or the name 
of a cataloged procedure that contains 
the name of a load module that is to 
be executed. The load module can be 
the COBOL compiler, the linkage 
editor, the loader, or any COBOL 
program in load module form. 

2. Accounting information for this job 
step. 

3. Conditions for bypassing the execution 
of this job step. 

4. Computing time for a job step or 
cataloged procedure step, and main 
storage region size. 

5. Compiler, linkage editor, or loader 
options chosen for the job step. 

Figure 6 is the general format of the 
EXEC statement. 

Note: If the information specified is 
normally delimited by parentheses but 
contains blanks, parentheses, or equal 
signs, it must be delimited by single 
guotation marks instead of parentheses. 



Identifying the St ep (stepname ) 

The stepname identifies a job step 
within a job. It must satisfy the 



Identify in< 
(PROP 



the Program {PGM] or P/rocedure 



The EXEC statement identifies the 
program to be executed in the job step with 
the PGM parameter. To specify the COBOL 
compiler, code the positional parameter in 
the first position of the operand field of 
the EXEC statement. 



PGM=IKFCBL00 



It indicates that the COBOL compiler is the 
processing program to be executed in the 
job step. 

To specify the linkage editor, code the 
positional parameter in the first position 
of the operand field of the EXEC statement. 



PGM=IE«L 



This indicates that the linkage editor is 
the processing program to be executed in 
the job step- 

The PGM parameter depends upon the type 
of library in which the program resides. 
If the job step uses a cataloged procedure, 
the EXEC statement identifies it with the 
PROC parameter, in place of the PGM 
parameter. 
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1 -r— 1 

Oper- 
ation 



Name 



Operand 



— 1 



//[ step name j 1 



EXEC 



Positional Parameters 

PGM=prognarae 
|PGM=*.stepname.ddname 

PR0C=procname 
Iprocname 
^PGM=*.stepname. procstep.ddnamej 

Keyword Pa r a met e rs 



Tacct* \ 

lACCT.procstepj = (accounting-information; 

TcOND 2 ) 

\coND. procstepj = ( (code, operator[ ,stepname[ - procstep] ]) 

7parh* "I 3 

(PARM. procstepj = (option£ , option ].. .) 

7time i 

(TIME, procstepj = (minutes, seconds, 

/REGION ) 

(REGION, procstepj = valueK 

7«D } 

\RD. procstepj = request 

/dprty ^ 

(DPRTY. procstepj 

JADDRSPC 1 (VIRT( 

(ADDRSPC. procstepj = ( 



(value 1, value 2) 

(VIRT) 
ADDRSPC. procstep/ = (REALJ 



-f 



*Stepname is required when information from this control statement is referred to in a 

later job step. 
2 If this format is selected, it may be repeated in the EXEC statement once for each 

step in the cataloged procedure. 
3 If the information specified contains any special characters except hyphens, it must 

be delimited by single quotation nfarks instead of parentheses. 
♦If accounting-information contains any special characters except hyphens, it must be 

delimited by single quotation marks. 
s The maximum number of characters allowed between the delimiting quotation marks or 

parentheses is 142. 
6 The maximum number of repetitions allowed is 7. 

7 If only one test is specified, the outer pair of parentheses may be omitted. 
•If the only special character contained in the value is a comma, the value may be 

enclosed in quotation marks. 
9 The maximum number of characters allowed between the delimiting quotation marks or 

parentheses is 100. 
i 

Figure 6. EXEC Statement 
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are temporary 
ts created to store 
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until it is 
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rom a temporary 
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statements for several steps, each of 
which executes a particular program. 
Cataloged procedures are members of a 
library named SYS 1. P80CLIB. To 
request a cataloged procedure, code 
the positional parameter in the first 
position of the operand field of the 
EXEC statement. 



PBQC=procnarae 



PGM=*. stepname. ddname 



The asterisk {*) indicates the current 
job step. Beplace the terms stepname 
and ddname with the names of the job 
step and the DD statement within the 
procedure step, respectively, in which 
the temporary library is created. 



If the temporary library 
a catalogued procedure s 
to call it in a later jo 
the procedure, give both 
the job step that calls 
and the procedure stepna 
the positional parameter 
position of the operand 
EXEC statement. 



is created in 
tep, in order 
b step outside 

the name of 
the procedure 
me by coding 

in the first 
field of the 



Replace the term procname with the 
unqualified name of the cataloged 
procedure {see "Using the DD 
Statement" for a discussion of 
qualified names). 

Note: A procedure may be tested before it 
is placed in the procedure library by 
converting it into an in-stream procedure 
and placing it within the job step itself. 
In-stream procedures are discussed in the 
section, "Testing a Procedure as an 
In-stream Procedure" in the chapter "Using 
the Cataloged Procedures." 



KEYWORD PARAMETERS 



PGM=*. stepname. procstepname. ddname | 



Specifying .Job .Step,,. Account ing Information 
(ACCT)" 



The system library is a partitioned 
data set named SYS1 .LIHKLIB that 
contains nonresident control program 
routines, and processor programs. To 
execute a program that resides in the 
system library, code the positional 
parameter in the first position of the 
operand field. 



When executing a multistep job, or a job 
that uses cataloged procedures, the 
programmer can use this parameter so that 
jobsteps are charged to separate accounting 
areas. To specify items of accounting 
information to the installation accounting 
routines for this job step, code the 
keyword parameter in the operand field of 
the EXEC statement. 



PGH=progname 



ACCT= (accounting information) 



Replace the term progname with the 
member name or alias associated with 
this program. This same keyword 
parameter can be used to execute a 
program that resides in a p riv ate 
library. Private libraries are made 
available to a job with a special DD 
statement (see "Additional DD 
Statement Facilities"). 
Instead of executing a particular 
program # a job step may use a 
catalo ged procedure. A cataloged 
procedure can contain control 



Replace the term "accounting information" 
with one or more subparameters separated by 
commas. If both the JOB and EXEC 
statements contain accounting information, 
the installation accounting routines decide 
how the accounting information shall be 
used for the job step. 



To pass acc6unting information to a step 
within a cataloged procedure, code the 
keyword parameter in the operand field of 
the EXEC statement. 
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I ACCT. procstep= (accounting inf oriaation) \ 

t j 



The compiler issues a return code of 1b 
when any of the following are detected: 



Procstep is the name of the step in the 
cataloged procedure. This specification 
overrides the ACCT parameter in the named 
procedure step, if one is present. 



Specifying Conditions for Bypassing or 
Executing the Jo b Step (COND) 



• BASIS member-name is specified and no 
member of that name is found 



• Required device not available 



• Not enough main storage is available 
for the tables reguired for compilation 



• A table exceeded its maximum size 



The execution of certain job steps is 
based on the success or failure of 
preceding steps. The COND parameter 
provides the means to: 

• Make as many as eight tests on return 
codes issued by preceding job steps or 
cataloged procedure steps, which were 
completed normally. If any one of the 
tests is satisfied, the job step is 
bypassed. 

* Specify that the job step is to be 
executed even if one or more of the 
preceding job steps abnormally 
terminated or only if one or more of 
the preceding job steps abnormally 
terminated. 



To specify conditions for bypassing a 
job step, code the keyword parameter in the 
operand field of the EXEC statement. 



J COND= ( (code, operator, [ stepname]) ,... , j 
| (code, operator, [stepname ])) | 

t j 



• A permanent input/output error has been 
encountered on an external device 



The return codes have a correlation with 
the severity level of the error messages. 
With linkage editor messages, for example, 
the rightmost digit of the message number 
states the severity level; this number is 
multiplied by 4 to get the appropriate 
return code. With the COBOL compiler, 04, 
08, 12, and 16 are equal to the severity 
flags: H, C, E, and D, respectively. 



The term "operator" specifies the test 
to be made of the relation between the 
programmer-specified code and the job step 
return code. Replace the term operator 
with one of the following: 

GT (greater than) 

GE (greater than or equal to) 

EQ (equal to) 

LT (less than) 

LE (less than or equal to) 

NE (not equal to) 



The term "code" may be replaced by a 
decimal numeral to be compared with the job 
step return code. The return codes for 
both the compiler and the linkaqe editor 
are: 

00 Normal conclusion 

04 Warning messages have been listed, 
but program is executable. 

08 Error messages have been listed; 
execution may fail. 

12 Severe errors have occurred; 
execution is impossible. 

16 Terminal errors have occurred; 

execution of the processor has been 
terminated. 



The term "stepname" identifies the 
previously executed job step that issued 
the return coda to be tested and is 
replaced by the naie of that preceding job 
step. If stepname is not specified, code 
is compared to the return codes issued by 
all preceding steps in the job. 

Replace the term stepname with the name 
of the preceding job step that issues the 
return code to be tested. 

If the programmer codes 

C0ND= ( (4,GT,STEP1) , (8 , EQ, STEP2) ) 

the statement is interpreted as: "If 4 is 
greater than the return code issued by 
STEP1, or if STEP2 issues a return code of 
8, this job step bypassed." 
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Igies: 



• If only one test is made, the 
programmer need not code the outer 
parentheses, e.g., COND= (12,EQ,STEPX) . 

• If each return code test is made on all 
preceding steps, the programmer need 
not code the terms stepaame, e.g., 
C0ND=({4,GT) ,{8,EQ)) . 

• When the return code is issued by a 
cataloged procedure step, the 
programmer may want to test it in a 
later job step outside of the 
procedure. In order to test it, give 
both the name of the job step that 
calls the procedure and the procedure 
stepname, e.g., COND={ (code, operator, 
stepname. procstep) ,...). 



Abnormal termination of a job step 
normally causes subsequent steps to be 
bypassed and the job to be terminated. By 
means of the COND parameter, however, the 
programmer can specify execution of a job 
step after one or more preceding job steps 
have abnormally terminated. For the COND 
parameter, a job step is considered to 
terminate abnormally if a failure occurs 
within the user's program once it has 
received control. (If a job step is 
abnormally terminated during scheduling 
because of failures such as job control 
language errors or inability to allocate 
space, the remainder of the job steps are 
bypassed, whether or not a condition for 
executing a later job step was specified.) 

To specify the condition for executing a 
job step, code the keyword parameter in the 
operand field of the EXEC statement. 



i 

I COND 



(even\ 

= (ONLY) 



The EVEN or ONLY subparameters are mutually 
exclusive. The subparameter selected can 
be coded in combination with up to seven 
return code tests, and can appear before, 
between, or after return code tests, e.g., 

COND= (EVEN, (4, GT, STEP 3) ) 

C0ND=((8,GE,STEP1), (1 6,GE) ,ONLY) 



The EVEN subparameter causes the step to 
be executed even when one or more of the 
preceding job steps have abnormally 
terminated. However, if any return code 
tests specified in this job step are 
satisfied, the step is bypassed. The ONLY 
subparameter causes the step to be executed 



only when one or more of the preceding job 
steps have abnormally terminated. However, 
if any return code tests specified in this 
job step are satisfied, the step is 
bypassed. 

When a job step abnormally terminates, 
the COND parameter on the EXEC statement of 
the next step is scanned for the EVEN or 
ONLY subparameter. If neither is speci- 
fied, the job step is bypassed and the EXEC 
statement of the next step is scanned for 
the EVEN or ONLY subparameter. If EVEN or 
ONLY is specified, return code tests, if 
any, are made on all previous steps 
specified that executed and did not 
abnormally terminate. If any one of these 
tests is satisfied, the step is bypassed. 
Otherwise, the job step is executed. 

If the programmer codes 

COND=EVEN 

the statement is interpreted as: "Execute 
this step even if one or more of the 
preceding steps abnormally terminated 
during execution." If COND=ONLY is coded, 
it is interpreted as: "Execute this step 
only if one or more of the preceding steps 
abnormally terminated during execution." 

If the COND parameter is omitted, no 
return code tests are made and the step 
will be bypassed when any of the preceding 
job steps abnormally terminate. 

Notes: 

* When a job step that contains the EVEN 
or ONLY subparameter refers to a data 
set that was to be created or cataloged 
in a preceding step, the data set will 
not exist if the step creating it was 
bypassed. 

• When a jobstep that contains the EVEN 
or ONLY subparameter refers to a data 
set that was to be created or cataloged 
in a preceding step, the data set may 
be incomplete if the step creating it 
abnormally terminated. 

• when the job step uses a cataloged 
procedure, the programmer can establish 
return code tests and the EVEN or ONLY 
subparameter for a procedure step by 
including, as part of the keyword COND, 
the procedure stepname, e.g., 
COND.procstepname. This specification 
overrides the COND parameter in the 
named procedure step if one is present. 
The programmer can code as many 
parameters of this form as there are 
steps in the cataloged procedure. 

* To establish one set of return code 
tests and the EVEN or ONLY subparameter 
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for all steps in a procedure, code the 
COND parameter without a procedure 
stepname. This specification replaces 
all COND parameters in the procedure if 
any are present. 



This will pass options to the compiler, 
linkage editor, loader, or object program 
when any one of them is called by the PGM 
parameter in the EXEC statement or to the 
first step in a cataloged procedure. 



Job steps following a step that 
abnormally terminates are normally 
bypassed. If a job step is to be executed 
even if a preceding step abnormally 
terminates, specify this condition, along 
with up to seven return code tests: 



To pass options to a compiler, the 
linkage editor, loader, or the execution 
step within the named cataloged procedure 
step, code the keyword parameter in the 
operand field. 



I//STEP3 EXEC PGM=CONVERT, 

{// COND=(EVEN, (4,EQ,STEP1)) ,.. 

i 



— t 
XI 

1 
i 



PARM. procstep= (option[ , option ]. . . ) 



Here, the step is executed if the return 
code test is not satisfied, even if one or 
more of the preceding job steps abnormally 
terminated. If a job step is to execute 
only when one or more of the preceding 
steps abnornally terminate, replace EVEN in 
the above example with ONLY. 

If the EXEC statement calls a cataloged 
procedure* the programmer can establish 
return code tests and the EVEN or ONLY 
subparameter for a procedure step by coding 
the COND parameter followed by the name of 
the procedure step to which it applies: 

i 1 

J//STEP4 EXEC ANALYSIS, COND. XI 

|// REDUCE={ (16, EQ,STEP4. LOOKUP) ,ONLY) ,... J 

i j 



Here, the cataloged procedure step named 
REDUCE will be executed only if a preceding 
job step has abnormally terminated and the 
procedure step named LOOKUP does not issue 
a return code of 16. The programmer can 
code as many COND parameters of this type 
as there are steps in the procedure. 



Any PARM parameter already appearing in the 
procedure step is deleted, and the PARM 
parameter that is passed to the procedure 
step is inserted. 



A maximum of 100 characters may be 
written between the parentheses or single 
guotation marks that enclose the list of 
options. The COBOL compiler selects the 
valid options of the PARM field for 
processing by looking for significant 
characters (usually three) of each key 
option word, when the keyword is 
identified, it is checked for the presence 
or absence of the prefix NO, as 
appropriate. The programmer can make the 
most efficient use of the option field by 
using the significant characters instead of 
the entire option. Figure 7 lists the 
significant characters for each option (see 
"Options for the Compiler" for an 
explanation of each). 



Pa ss ing Information to the Processin g 
Program (PARM) 



For processing programs that require 
control information at the time they are 
executed, the EXEC statement provides the 
PARM parameter. To pass information to the 
program, code the keyword parameter in the 
operand field. 



PARM= (option[ , option ]. . . ) 
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1 — ' - - — 1 


r 




Significant 


J Option 1 


Characters 


J ADV 


ADV 


\ APOST j 


APO 


| BATCH 


BAT 


| BUF ] 


BUF 


J CDECK 


CDE 


J CLIST 


CLI 


\ CSYNTAX J 


CSY 


} COUNT 


COU 


| DECK 1 


DEC 


J DHAP I 


DMA 


j DUMP 


DUM 


} DYNAM 


DYN 


I END JOB 


END 


1 FDECK 1 


FDE 


1 FLAGE{W) 


LAG, LAGW 


J FLOW 


FLO 


1 LANGLVL 


LANGLVL 


| LCOL1/LCOL2 


OL1/OL2 


\ LIB 


LIB 


| LINECNT 


CNT 


| LOAD 


LOA 


J LSTONLY/LSTCOMP 


LSTO/LSTC 


\ LVL 


LVL 


J L 13 2/L 120 


L13/L12 


| NAME 


NAM 


J NUH | 


HUH 


J OPTIMIZE 


OPT 


J PMAP 


PMA 


| PBINT 


PRI 


J QUOTE 


QUO 


J RESIDENT 


RES 


3 S EQ 


SEQ 


| SIZE 


I siz 


\ SOURCE 


SOU 


J SPACE 


! ACE 


| STATE 


STA 


I SUPMAP 


| SUP 


J SXREF 


SXR 


I SYMDMP 


| SYM 


J SYNTAX 


| SYN 


\ SYSX 


I SYS 


| TERM 


I TER 


J TEST 


| TES 


| TRUNC 


TRU 


I VBSOM 


I VBS 


| VBREF 


j VBR 


J VERB 


| VEB 


1 XREF 


| XRE 


J ZWB 


| ZWB 



discussion can be changed when the compiler 
is installed. The format of the PARM 
parameter is illustrated in Figure 8. 



Notes: 



Characters for 
ions 



Figure 7- Significant 
Compiler opt 

Note: The compiler recognizes the 
significant characters to set the proper 
options. If an option is incorrectly 
spelled, the compiler default option is 
used. 

options for the Compiler 



The IBM-supplied default options 
indicated by an underscore in the following 



When a subparameter contains an equal 
sign, the entire information field of 
the PARM parameter must be enclosed by 
single quotation marks instead of 
parentheses, e.g.. 



PARM=«SIZE=160000,PMAP». This is the 
recommended (that is, raost efficient) 
technique, other ways of specifying 
special characters in the PARM 
parameter are described in QS /VS JCL 
Reference. 

• When an option and its default (such as 
XREF and NOXREF) are both specified, 
the last encountered option is 
generally the one assumed. {Exceptions 
to this rule are cited in the option 
descriptions.) Accordingly, the 
programmer may change one of the many 
options without, repunching the entire 
EXEC card. 

SIZE=yyyyyyy 

indicates the amount of main storage, 
in bytes, available for compilation 
{see "Machine Considerations") . The 
COBOL default value is 131,072 bytes, 
or 128K. 

BUF=yyyyyy 

indicates the amount of main storage 
to be allocated to buffers. If both 
SIZE and BUF are specified, the amount 
allocated to buffers is included in 
the amount of main storage available 
for compilation {see "Appendix D: 
Compiler Optimization" for information 
about how buffer size is determined) . 

Note: The SIZE and BUF compi le-tirae 
parameters can be given in multiples 
of K, where K=1024 decimal bytes. For 
example, 131,072 decimal bytes can be 
specified as 128K. 

LANGLVL (1/2) 

specifies whether the 1968 or the 1974 
American National Standard COBOL 
definition (as understood and 
interpreted by IBM) is to be used when 
compiling those source elements whose 
meaning has changed. LANGLVL (1) tells 
the compiler to use the 1968 ANS 
standard (X3. 23-1 968) if the compiler 
encounters any of those source 
elements whose definition has changed; 
this interpretation would be the one 
that was used by Release 1 of the 
compiler. LANGLVL (2) tells the 
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compiler to use the 1974 ANS 

s t andard ( X3 .23-1974) when 

encountering any of those redefined 
elements. LANGLVL(2) is the default. 



Generally speaking, the language 
level supported by the Release 2 
compiler includes all of that 
supported by Release 1 . The Release 2 
compiler will accept not only source 
programs written in the new (197 4) 
language , but also source programs 
that were or are written in the older 
(196 8) language. However, the 
superset relationship between the new 
and the older languages is not 
absolute; there are a few exceptions — 
elements whose meaning has changed 
because of ANS redefinition. It is 



only these few elements that are 
controlled by the LANGLVL option, 



(These elements are identified in 
Section III of Appendix A of IBM 
VS COBOL for OS/VS . ) Language 
elements whose meanings did not 
change from 1968 ANS to 1974 ANS 
(the vast majority of the language) 
are unaffected by the LANGLVL option, 
as are all IBM extensions and those 
language elements new in the 1974 
ANS definition. The compiler accepts 
all such elements regardless of the 
LANGLVL specification. LANGLVL 
affects only that small percentage of 
elements whose definition changed from 
1968 to 1974. 
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The LANGLVL specification does affect 
the operation of the FIPS flagger. 
When the FIPS LVL option has been 
specified, selecting the 1968 ANS 
standard will cause FIPS flagging to 
be done to those corresponding 
specifications; selecting the 1974 ANS 
standard causes FIPS flagging to be 
done according to the newer 
specifications. 

SOUBCE 
NOSOORCE 

indiqates whether or not the source 

module is to be listed. 



CLIST 

NOCLIST 

indicates whether or not a condensed 
listing is to be produced. If 
specified, the procedure portion of 
the listing will contain generated 
card numbers {unless the NOM option is 
in effect) , verb references, and the 
location of the first instruction 
generated for each verb. Global 
tables, literal pools, register 
assignments, and information about the 
Working-Storage section are also 
provided. CLIST and PMAP are mutually 
exclusive options. (If both are 
specified, COBOL rejects the one 
specified first.) 

No£e: In nonsegmented programs, verbs are 
listed in source order. In segmented 
programs, the root segment is first, 
followed by the individual segments in 
order of ascending priority. 



DMAP 

NO DMAP 

indicates whether or not a glossary is 
to be listed. Global tables, literal 
pools, register assignments, and 
information about the Working-Storage 
Section are also provided. 

PHAP 

NOPMAP 

indicates whether or not register 
assignments, global tables, literal 
pools, information about the 
Working-Storage Section, and an 
assembler-language expansion of the 
source modules are to be listed. 
CLIST and PMAP are mutually exclusive 
options. {If both are specified, 
COBOL rejects the one specified 
first.) 

I2£§: If any one of the options CLIST, 
DMAP, and PMAP is specified, the compiler 
will produce a message giving the 
hexadecimal length and starting address of 
the Working Storage Section. For an 



illustration of the use of these options, 
see the "output" section. 



VERB 

NO VERB 

indicates whether procedure-names and 
verb-names are to be listed with the 
associated code on the object- program 
listing. VERB has meaning only if 
PMAP or CLIST is in effect. VERB is 
automatically in effect if SYMDMP, 
STATE, or TEST is in effect. NOVERB 
yields more efficient compilation. 

Note; If READY TRACE debugging 
statements are used in the program, 
VERB will cause paragraph-names rather 
than card numbers to be displayed at 
execution time. 

LOAD 

NOLO AD 

indicates whether or not the object 
module is to be placed on a mass 
storage device or a tape volume so 
that the module can be used as input 
to the linkage editor. If the LOAD 
option is used, a SYSLIN DD statement 
must be specified. 



DECK 

S0_2I££ 

indicates whether or not the object- 
module is to be punched. If the DECK 
option is used, a SYSPONCH DD 
statement must be specified. 



NOSEQ 



indicates whether or not the compiler 
is to check the sequence of the source 
module statements. If the statements 
are not in sequence, a message is 
printed. 



Note: For examples of what the SOURCE, 
DMAP, PMAP, and SEQ options produce, see 
"Output." 



LINECNT=nn 

indicates the number of lines to be 
printed on each page of the 
compilation source card listing. The 
number specified by nn must be a 
2-digit integer from 01 to 99. If the 
LINECNT option is omitted, 60 lines 
are printed on each page of the output 
1 is ting. 
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Note: The compiler requires three 
lines of what the user has specified 
for its headings. (For example, if 
nn=55 is specified, then 52 lines are 
printed on each page of the output 
listing.) 



ZWB 

NOZWB 

indicates whether or not the compiler 
generates code to strip the sign from 
a signed external decimal field when 
comparing this field to an 
alphanumeric field. If ZWB is 
specified, the signed external decimal 
field is moved to an intermediate 
field, in which its sign is removed, 
before it is compared to the 
alphanumeric field. ZWB complies with 
the ANS standard; NOZWB should be used 
when, for example, input numeric 
fields are to be compared with SPACES. 

LVL=A/B/C/D 

specifies what level of FIPS (Federal 
Information Processing Standard) 
flagging is to be used.' A~,~ B, C, and 
D correspond to the levels Low, 
Low- Intermediate , High- Intermediate , 
and Full, respectively. If flagging 
is specified, source clauses and 
statements that do not conform to the 
specified level of FIPS are 
identified. See the publication IB M 
VS COBOL for QS/VS for a complete list 
of the statements flagged at each 
level. 



Notes 



If LVL is the SYS GEN default, its 
assigned value can be overridden 
at compile time with any level 
except NOLVL. If NOLVL is the 
SYSGEN default, it can be 
overridden at compile time with 
any level. 

If the LVL option is in effect, 
the SYSUT6 data set must be 
specified. 

If both LVL=A/B/C/D and TEBH are 
specified, the compiler listing 
output to SYSPRINT for options 
such as SOURCE, PHAP, and XBEF are 
not produced. 

The option SOURCE is automatically 
turned on if LVL is specified. If 
TERM is off, a listing is produced. 
If TERM is on, there is no listing. 
(See note 3.) 

If both LVL and BATCH are 
specified, LVL is rejected. 



The LANGLVL option controls the 
version of FIPS that will be used. 
Reguesting LANGLVL(1) — the 1968 
ANS standard—causes flagging to 
be done according to the 1972 FIPS 
specifications. Requesting 
LANGLVL <2) — the 1974 ANS 
standard--causes flagging to be 
done according to the 1975 FIPS 
speci fications. 

Generally, FIPS flagging will not 
be done if the compiler has 
detected any source errors (that 
is, if the return code is not 
zero) . The only exceptions 
concern a few w- level messages 
(such as IKF1100-W) that are 
purely informational; detecting 
these will not prevent FIPS 
flagging. The FLAGE option should 
not be used, since W-level messages 
will not be listed and results are 
unpredictable . 

If the compiler detects a 
D-level error, FIPS will not 
execute, nor will any of the 
compiler's usual messages or 
listings be produced. A 
return code of 1 6 will be the 
only indication that this has 
occurred. To overcome this 
difficulty, recompile with a 
specification of NOLVL, then 
remove the source errors as 
indicated by the compiler, and 
finally recompile again with LVL. 

indicates the type of messages that 
are to be listed for the compilation. 
FLAGW indicates that all warning and 
diagnostic messages are to be listed. 
FLAGE indicates that all error 
messages are to be listed, but that 
the warning messages are not to be 
listed. Note. With the use of 
FLAGE, and only W-level errors, the 
return code will be zero. 

SOPMAP 

NOSUPMAP 

indicates whether or not the object 
code listing, and object module and 
link edit decks are to be suppressed 
if an E-level or D-level message is 
generated by the compiler. 

SPACER 

SPACE2 

SPACE3 

indicates the type of spacing that is 
to be used on the source card listing 
generated when SOURCE is specified. 
SPACE1 specifies single spacing, 
SPACE2 specifies double spacing, and 
SPACE3 specifies triple spacing. 



Os£GW 
FLAGE 
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TBUNC 

SOTRUNC 

applies to movement of COMPUTATIONAL 
arithmetic fields. If TRUNC (standard 
truncation) is specified and the 
number of digits in the sending field 
is greater than the number of digits 
in the receiving field, the arithmetic 
item is truncated to the number of 
iigits specified in the PICTURE clause 
of the receiving field when moved. If 
NOTRUNC is specified, movement of the 
item is dependent on the size of the 
field (half word, f ullword) . 

apost 

indicates to the compiler that either 
the double quote ( M ) or the apostrophe 
(•) is acceptable as the character to 
delineate literals and to use that 
character in the generation of 
figurative constants. 

STATE 

NO ST ATE 

indicates whether or not the number of 
the COBOL statement being executed at 
the time of an abnormal termination is 
desired. STATE identifies the number 
of the statement and the number of the 
verb being executed. If the STATE 
option is used, a SYSDBOUT DD 
statement must be specified at 
execution time for the output data set 
on which the statement number message 
can be written. For more information, 
see "Debugging Facilities" in the 
chapter "Program Checkout." 

FLOW£=nn] 

NOFLOS 

indicates whether or not a formatted 
trace is desired for a variable number 
of procedures executed before an 
abnormal termination. The number of 
procedures traced is specified by nn, 
where nn may be any integer value from 
one to 99. FL0W[=nn] must be 
specified at compile time to generate 
the necessary trace linkage; however, 
specifying nn may be deferred until 
execution time. If nn is omitted, the 
default value is employed. This value 
is either 99 or that specified at 
program product installation. 
Specifying NOFLOW at compile time 
precludes specification of the Flow 
Trace option at execution time. A 
SYSDBOUT DD statement must be included 
for the output data set on which the 
trace can be written. See "Options 
for Execution" for more Information. 



SYMDMP 

NOSYMDMP 

reguests a formatted dump of the data 
area of the object program at abnormal 
termination. With this option, the 
programmer may also request dynamic 
dumps of specified data-names at 
strategic points during program 
execution, see "symbolic Debugging 
Features" for more information. 

Notes; 



1. If the SYMDMP option is in effect, 
the SYSUT5 data set must be 
specified, and the NULLFILE or 
DUMMY parameter should not be 
specified on its DD statement. 

2. If the BATCH option is requested, 
SYMDMP is rejected. 

3. If WITH DEBUGGING MODE is 
specified and one or more USE FOR 
DEBUGGING statements are in the 
program, the SYMDMP option is 
rejected. 

4. Specification of the SYMDMP option 
automatically yields the OPTIMIZE 
feature, discussed below, and 
rejects the STATE option because 
SYMDMP output includes STATE 
output at abnormal termination. 

For a discussion of the FLOW, STATE, and 
SYMDMP options, and their value to the 
COBOL programmer, see the chapter entitled 
"Symbolic Debugging Features." A SYSDBOUT, 
SYSDBG, and debug file DD codes are 
required at execution time, 

OPTIMIZE 

NOOPTI HIZE 

causes optimized object code to be 
generated by the compiler, 
considerably reducing the use of 
object program main storage. In 
general, the greater the number of 
COBOL Procedure Division source 
statements, the greater the percentage 
of reduction in the amount of main 
storage required. 

l2Jk£* The optimizer feature is 
automatically in effect when the 
SYMDMP or TEST feature is specified. 
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SYNTAX 

CSYNTAX 

NOSYNTAX 

NOCSYNTAX ' ' 

indicates whether object code 
generation is to be suppressed- — that 
is,' whether the compiler will only 
scan the source text for syntax errors 
(with appropriate error messages being 
produced) - 

SYNTAX causes syntax checking only, 
with absolute suppression of object 
code generation. 

CSYNTAX causes syntax checking with 
conditional object code generation: a 
full compilation is produced as long 
as no errors exceed the W or C level; 
if one or more E-level or higher 
severity errors are discovered, the 
compiler does not generate the object 
code. 

NOSYNTAX causes normal compilation, 
with both syntax checking and object 
code generation. 



Notes: 

1. When the SYNTAX option is in 
effect, all of the following 
compile-time options are 
suppressed: 



LOAD 


DECK 


NAME 


XREF 


SYMDMP 


COUNT 


SXREF 


TRUNC 


VBSUM 


CLIST 


OPTIMIZE 


VBREF 


NOSUPMAP 


FLOW 


DMAP 


PMAP 


STATE 





Unconditional syntax checking is 
assumed if ail of the following 
compile-time options are 
specified: 



NOLO AD 
NOXREF 
NOSXREF 



NOCLIST 

NOPMAP 



SOPMAP 
NODECK 



a DMAP) , depending on how much work 
the compiler had completed before 
the error was discovered. 



5. When CSYNTAX has been specified 
and an E-level or higher error is 
detected, the final parts of the 
compilation procedure execution of 
phases 60, 62, 63, or 64 (which deal 
with code generation) are not 
executed. Because of this, any 
existing syntax errors that could 
only be detected by these latter 
phases of compilation will not be 
discovered and made known to the 
user during the CSYNTAX run; they 
will only come to light during a 
later full compilation- 



NUM 
NONUM 



indicates whether or not line numbers 
have been recorded in the input and, 
rather than compiler-generated source 
numbers, should be used in error 
messages, as well as in PMAP, CLIST, 
STATE, XREF, SXREF, and FLOW. NONUM 
indicates that the compiler-generated 
numbers should be used in error 
messages as well as in PHAP, CLIST, 
STATE, XREF, SXREF, and FLOW. 



Note: if when the 
effect the compiler 
non-numeric charact 
or if ascending num 
broken, the compile 
number. The compil 
last valid card num 
adds a 1 to that nu 
generating card num 
point. The increme 
digits is the maxim 
The card that folio 
flagged and NUM, SY 
canceled. STATE an 
canceled. 



NUM option is in 
discovers a 
er in a line number 
eric sequence is 
r invalidates the 
er then takes the 
ber in sequence, 
mber and begins 
bers from that 
nt is 1. Six 
um sequence number, 
ws 99999 9 will be 
MDMP, and TEST 
d FLOW will not be 



CSYNTAX and SYNTAX are mutually 
exclusive. CSYNTAX will override 
SYNTAX. 

If CSYNTAX is specified and an E 
or D-level diagnostic message is 
encountered before or during the 
operation of phase 21 or during 
the operation of phases 30, 40, 
45, 50, or 51, the SYNTAX option 
replaces CSYNTAX, and the options 
listed in Note 1 above are sup- 
pressed. However, certain types of 
output may be produced (for example, 



If LSTCOMP is in effect, the statement 
number generated by the lister feature 
is used regardless of NUM or NONUM 
specification. 



XREF 

SOXREF 

indicates whether or not a 
cross-reference listing is produced. 
If XREF is specified, an unsorted 
listing is produced with data-names 
and procedure- names appearing in two 
parts in source order. 
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SXREF 

NOSXREF 

indicates whether or not a sorted 
cross-reference listing is produced. 
If SXREF is specified, a sorted 
listing is produced with data-names 
and procedure-names in alphanumeric 
order. 

Notes; 

• XREF and SXREF are mutually 
exclusive. If both are specified, 
COBOL rejects the one specified 
first. 

• Some data names used in STRING, 
UNSTRING, SEARCH, and USE FOR 
DEBUGGING statements are not part of 
the compiler-generated code, and 
therefore will not appear in an XREF 
or SXREF listing. 

• Group names in a MOVE CORRESPONDING 
statement will not be listed in an 
XREF or SXREF listing; however, the 
elementary names within those groups 
will be listed. 

• Because most of the Report Writer 
code is generated before the com- 
piler creates the dictionary, most 
of the Report Writer data names do 
not appear in an XREF or SXREF 
listing. 



LIB 

IQilB 

indicates whether or not a COPY and/or 
a BASIS request will be part of the 
COBOL source input stream. If no 
library facilities are to be used, the 
specification of NOLIB will save 
compilation time. 

BATCH 

NOBATCH 

indicates whether or not multiple 
programs and/or subprograms are to be 
compiled with a single invocation of 
the compiler. In the BATCH 
environment all compiler options 
specified on the EXEC card, plus all 
default options, will apply to every 
program in the batch unless specific 
options are overridden on the CBL 
card, which must be included for each 
program, see "Batch compilation" for 
more information on batch compilations 
and the CBL card. 

When BATCH is specified, the LVL and 
SiMDMP options will be rejected. In 
addition, the BUF, L120/L132, and SIZE 
options are precluded from use on a 
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CBL card and will be rejected if 
specified. 



NAME 

NONAJill 

indicates whether or not programs in a 
batch compilation environment will be 
link-edited into one or more load 
modules. If NAME is specified, each 
succeeding program in the batch will 
be link-edited into a separate load 
module. This option will remain in 
effect for the entire compilation 
unless NONAME is specified on the CBL 
card for an individual program. If 
NONAME is specified on the CBL card, 
no name will be generated for this 
compilation. Names for the load 
modules will be formed according to 
the rules for forming module names 
from the PROGRAM-ID. See "Batch 
Compilation" for more details on batch 
compilation and the CBL card. 

Note: If the BATCH option is not 
specified, NONAME will be in effect. 

RESIDENT 

N08ESIDENT 

requests the COBOL Library Management 
feature, when one program in a given 
region/partition requests the RESIDENT 
option, the main program and all 
subprograms in that region/partition 
should also request it. 

Note: The RESIDENT option is 
automatically in effect when the DYNAM 
option is invoked. 

DYNAM 

NQPyNAM 

causes subprograms invoked through the 
CALL literal statement to be 
dynamically loaded and through the 
CANCEL statement to be dynamically 
deleted at object time {instead of 
link-edited with the calling program 
into a single load module). 



Note: When both NO 
NODYNAM are either 
implied by default, 
identifier statemen 
source statement be 
COBOL Library Manag 
option (RESIDENT) i 
effect. A printed 
is given in the com 
a discussion of the 
Management Facility 
"Sharing COBOL Libr 
the "Libraries" cha 



RESIDENT and 
specified or 

and a CALL 
t occurs in the 
ing compiled, the 
ement Facility 
s automatically in 
statement of this 
piler output. (For 

COBOL Library 
, see the section 
ary Subroutines" in 
pter.) 



where x must be alphanumeric (that is, 
0-9 or A-z except for T) , is the 
ddname of the file to be used for 
debug output (READY TRACE, EXHIBIT) or 
DISPLAY statement. The specification 
in the program that is first to access 
the file is chosen. 



ENDJOB 

IOENMOB 

indicates 
of each r 
begin wit 
program c 
subroutin 
delete mo 
acquired 
COBOL lib 
takes eff 
any progr 
in a main 
the restr 
NORES mod 
cause an 
abend whe 
in progra 
without E 



whether or not, at the end 
un-unit (which is assumed to 
h the highest-level COBOL 
ailed) , the COBOL library 
e ILBOSTT0 is to be called to 
dules and free main storage 
through GETMAINs issued by 
rary subroutines. ENDJOB 
ect either at a STOP RUN in 
am, or at a GGBACK statement 

program only. Violation of 
iction against mixing RES and 
ules within a run-unit may 
unpredictable execution-time 
n ENDJOB is in effect, even 
ms which ran successfully 
NDJOB. 



SYST 
SYSx 



indicates whether SYSOUT or SYSOUx, 



Noj^e: Hhen a non-COBOL program, such 
as IMS or an installation-defined 
assembler program, links to COBOL load 
modules many times within a job step, 
the resulting accumulation of 
GETMAIN-acquired areas and loaded 
modules may result in execution-time 
abends. In order to prevent 
fragmentation and overload of storage 
in such an environment, the ENDJOB 
compiler option must be specified. 
This will cause ILBOSTT0 to be loaded 
at the normal termination of the 
run-unit to free all GETMAIN areas 
and, in a RES environment, to delete 
any loaded subroutines and 
dynamically-invoked subprograms. The 
only GETMAIN areas not freed by 
ILBOSTT0 are those obtained when 
opening a random indexed BISAM file 
for which the options APPLY CORE-INDEX 
and/or TRACK -ARE A IS integer 
CHARACTERS have been specified; before 
terminating, the user should close 
such files within the COBOL program. 

Since ILBOSTT0 is always loaded, it 
must be made available at execution 
time (by placing it in the link pack 
area or by specifying the COBOL 
library on a STEPLIB DD statement for 
the GO step). If ILBOSTTO is not 
placed in the link pack area, it 
should be explicitly deleted by the 
invoker of the COBOL run- unit; 
otherwise, one copy of this subroutine 
will remain in the user region after 
the run-unit has completed. 
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NOADV 

indicates whether or not records for 
files with SRITE. .. ADVANCING need 
reserve the first byte for the control 
character. ADV specifies that the 
first byte need not be reserved, but 
that the compiler will add one byte 
to the LRECL for the control 
character. 

COUNT 

NOCOONT 
~ indicates whether or not code is to be 
generated to produce verb execution 
summaries at the end of problem 
program execution. Each verb is 
identified by procedure-name and by 
statement number, and the number of 
times it was used is indicated. In 
addition, the percentage of verb 
execution for each verb with respect 
to the execution of all verbs is 
given. A summary of all executable 
verbs used in a program and the number 
of times they are executed is 
provided. COUNT implies VERB. COUNT 
requires both SYSDBOUT and SYSCOUNT 
DD statements at execution time. For 
a more detailed discussion on the use 
of the COUNT option, see the chapter 
"Program Checkout." 

DUMP 

NODUMP' 

specifies whether the compiler should 
produce a dump or an informative 
message in the event it encounters a 
D-level ("disaster") error condition 
during its processing. The compiler 
will abnormally terminate after pro- 
ducing the dump /message. 

DUMP specifies that a dump (but no 
message) is to be produced. This dump 
will contain a four-digit user 
completion code. See Appendix K for 
more information on these codes . 
( Note ; The most frequent cause of 
compiler abend is insufficient SIZE 
value — a user completion code of 0003. 
In this case , rerun the program spec- 
ifying a larger value.) 

NODUMP specifies that the compiler is 
to produce an informative message 
(but no dump) . 

If analysis of the message or dump 
does not solve the problem, see 
Appendix L for the procedure to follow 
in calling IBM for assistance. 



count of how often each verb appeared, 
This option provides the user with a 
quick search for specific types of 
statements. VBSUM implies VERB. 



VBSUM 
NOVBSUM 



VBREF 
NOVBREF 



provides a cross-reference of all 
verbs used in the program. This 
option provides the programmer with 
a quick index to any verb used in 
the program. VBREF implies VERB 
and VBSUM. 



Qptjons .for the Lister Feature 



There are five compiler options for using 
the lister feature of the compiler. Note 
that either LSTONLY or LSTCOMP must be 
selected for the other four options to have 
meaning unless the BATCH option is 
specified. In a batch compilation, if some 
or all of the programs are to be compiled 
using the lister feature, L120 or L132 must 
be specified in the PARM field of the EXEC 
card, even if LSTCOMP or LSTONLY are to be 
specified on the CBL card. 

For detailed information on the use of the 
lister, see the chapter "The Lister 
Feature." The options are listed in Figure 
6 , where : 



LSTONLY 

LSTCOMP 

NOLST 

indicates whether the lister feature 
is to be used. LSTONLY specifies that 
a reformatted listing is to be 
produced but that no compilation is to 
occur. LSTCOMP specifies that both a 
reformatted listing is to be produced 
and compilation is to occur in the 
same job step. 



FDECK 

NOFDECK 

indicates whether a copy of the 
reformatted source program is to be 
written on the SYSPUNCB data set. 
Since FDECK has meaning only with 
either LSTONLY or LSTCOMP, the lister 
output will be both a reformatted 
listing and a reformatted deck. 



CDECK 
NOCDECK 



provides a brief summary of verbs 
used in the source program and a 



indicates whether or not COPY 
statements are to be expanded into 
COPY members in the SYSPONCH output. 
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The COPY members are to be expanded in LC0L1 

the reformatted deck requested through LCOI.2 

FDECK. If CDECK is specified »ith indicates whether the Procedure 

NOFDECK, only the expanded COPY Division part of the listing is to be 

statements are produced. in single or double column format. 
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L120 
L132 



indicates whether the length of each 
line of the reformatted listing is to 
be 120 or 132 characters long. 



Options for Dse Under TSO Only 



Time sharing provides the COBOL programmer 
with facilities for entering, compiling, 
and testing programs at his terminal. (For 
further information on the Time Sharing 
Option, see the Program Product publication 
IB M OS (TSO) : COBOL Prompter Terminal 
Oser «s , Qi t ide and Refere nce. ) These options 
are listed in Figure 8, where: 



In addition to the preceding compiler 
options, the following options are designed 
for *ise with the Time Sharing Option (TSO). 
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Compiler: 

fPABM ) 

(PARM. procstep/ 



= C[SIZE=yyyyyyyJ[,BUF=yyyyyy3[,LANGLVL{1/2) ] 



f,PMAP 
[f N QP H A £ 



,SUPMAP 
.NOSUP 



C , LINECNT=nn] 



,spacei: 

,SPACE2 
_,SPACE3_ 

, BATCH 
,NOBATCH 



,SYMDHP 
#IOSXMDH£ 

,TEST ♦' 

#I£XE£X 



^RESIDENT 
CORESIDENT 



,ADV 
,NOADV 



f FDECK * 
#IO£2££I 



,TRUNC 
, NOTRU 



p 1 

l£j 



, STATE 
.NOSTATE 



,FLOW[=nn ] 

.NQFLOB 

^OPTIMIZE 
.NOOPTIfllZff 



,ENDJOB 
.NOENDJOB 

,DYNAM 
rNODYNAH 

, COD NT 
,NOCOUNT 



,CDECK & 
. NOCDECK 



LlOAD 
[, NO LOAD 

r,CLIST 
[,NOCLI5T 

, XR EF 
, NO XR EF 



,TERM * 
,NOTER8 

, SYNTAX 
, NO SYNTAX 



\* SOURCE I [,DHAP 1 

L nosodrceI . nodhap 

1 [,SE2 1 

kJ [, noseqJ 

ill \t 220T El 

;eJ [,apostJ 
~, sxref 1 [,name 1 

, N SXR EF | [, NONAHgj 



,DECK 
»NQfiI£K 

*1LkMk 
,FLAGE 



) 5 

snatej 



,P8INT /(* 
, NO PR I N2 \{d 

£ # LVL=A/B/C/D] 



) ■} 



,CSYNTAX 1 LlIB 1 [~,NUH 

» M> CS Y NTAXJ L'S2ltISj |_'-°--^ 

1 r#Zil 1 TrSYST 

J [,noz»bJ |_,sysx 



, NO VERB 

#MH£ 
, NO DUMP 



,L120 



[,LSTONLY *~| ,LC0L1 « 
,LSTCOMP LLCOL2 
rIOLST J 



, VBSUH 
,NO?BSPH 



,VBREF 
,NOVBREF 
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Linkage Editor: 

(PA8M 

(PARM. procstep 



} -A 



MAP \ 
XREFJ 



£,LIST] £,OVLY]) 



Loader: 



PARK } 

l^PARH. procstepj 



= ( 



HAP 
NOMAP 



| 

Execution: 

(PARM 

(PARM. procstep 



[ ,EP=nane ] 



"#IIS 1 [fCALJ. 1 

,NORESJ [,NOCALLj 

L PR INT "I 
[.NO PRINT J 



r,LET i r 



",SIZE=100k1 
,SIZE=sizeJ 



/PARM \ [~ FI " 0i, £ =nn ] 

j = {[user 



[# 21222 1 
, NODE BOG [f 



parameters]/ [ N OF LOW | 

[~, AIXBLD "I 

[.NOAIXBLD j £, QUEUE (value-list) ]) »«3 



UPS I (nnnnnnnn) ] 



*If the information specified contains any special characters, it must be delimited by 

single quotation marks instead of parentheses. 
*If the only special character contained in the value is a comma, the value may be 

enclosed in parentheses or quotation marks. 
3The maximum nuober of characters allowed between the delimiting quotation marks or 

parentheses is 100. 
♦These options should be used in the Time Sharing environment only. 
sTSO-only format. 
*These options are used to request the lister feature. 

i ; . — 

Figure 8. Compiler, Linkage Editor, and Loader PARH Options 
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PRINT 



NOP R 1ST 

indicates whether o 
listing is to be su 
the output data set 
dsname, or displaye 
If PRINT is specifi 
will include page h 
numbers of the stat 
message identificat 
severity levels, an 
well as any other o 
SOURCE, CLIST, DMAP 
SXREF). If (*) is 
of data-set name, t 
is sent to the term 
alone is specified, 
is created on secon 
named according to 
naming conventions, 
that no listing is 
neither PRINT nor N 
specif iedand any on 
options SOURCE, CLI 
PMAP are specified, 
default. Otherwise 
default. If PRINT 
non-TSO environment 



r not the program 
ppressed, placed on 

specified by 
d at the terminal, 
ed, the listing 
eadings, line 
ements in error, 
ion numbers, 
d message texts (as 
utput requested by 
, PMAP, XREF, or 
specified instead 
he printed output 
inal. If PRINT 

a listing data set 
dary storage and 
standard data set 

NOPRINT specifies 
to be printed. If 
OPRINT is 
e or more of the 
ST, DMAP, XREF, or 

PRINT is the 
, NOPRINT is the 
is specified in a 
, it is ignored. 



TERM 

NOTERH 

indicates whether or not progress and 
diagnostic messages are to be printed 
on the SYSTERM terminal data set. The 
severity level of the messages may be 
controlled by the FLAG option. If 
PRINT (*) is specified, then NOTERM is 
the default, to ensure that messages 
appear only once. If TERM is 
specified in a non-TSO environment, 
the output that normally goes to the 
SYSTERM DD data set is written on the 
SYSTERM file if a SYSTERM DD card has 
been included. If there is no SYSTERH 
DD card, a warning message is issued. 



TEST 

NOTEST 

indicates whether or not the program 
can be debugged at the terminal using 
the program product IBM OS COBOL 
Interactive Debug (Program Number 
5734-CB4). A program that is compiled 
without the TEST option is 
unacceptable to the Interactive Debug 
command processor. Complete 
information on COBOL Interactive Debug 
is contained in IBM OS, COBOL 
Interactive Debug T er minal User's 
Guide and Ref erence . 

When TEST is in effect, the COBOL 
compiler produces optimized object code 
When you specify TEST, you cannot also 



specify FLOW, STATE, COUNT, SYMDMP, or 
BATCH. 

If the TE^T option is in effect, the 
SYSUT5 data set must be specified. 

The TEST option is rejected if both 
WITH DEBUGGING MODE is specified and 
one or more USE FOR DEBUGGING 
statements are in the program. 



Options for the Link age Editor 



MAP 



XREF 



LIST 



OVLY 



indicates that a map of the load 
module is to be listed. If MAP is 
specified, XREF cannot be specified, 
but both can be omitted. 



indicates that a cross-reference list 
and a module map are to be listed. If 
XREF is specified, MAP cannot be 
specified. 

indicates that any linkage editor 
control statements associated with the 
job step are to be listed. 



indicates that the load module is to 
be in the format of an overlay 
structure. This option is required 
when the COBOL Segmentation feature is 
used. 



The format of the PA 
illustrated in Figure 8 
what the MAP, XREF, and 
produce, see "Output." 
control statements and 
are explained in "Calli 
Programs." There are o 
for linkage editor proc 
additional processing o 
attributes of the load 
publication Q5/Y§_Linka 
Loader) . 



Options for the Loader 



RM parameter is 
For examples of 

LIST options 

Linkage editor 
overlay structures 
ng and Called 
ther PARM options 
essing that describe 
ptions and special 
module (see the 
ge, Editor and 



MAP 
NOMAP 



indicates whether or not a map of the 
loaded module is to be produced that 
lists external names and their 
absolute addresses on the SYSLOUT data 
set. If the SYSLOUT DD statement is 
not used in the input deck, this 
option is ignored. An example of a 
module map is shown in "Output." 
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RES 

NQHES 

indicates whether or not an automatic 
search of the link pack area queue is 
to be made. This search is always 
made after processing the primary 
input (SYSLIN) , and before searching 
the SYLIB data set. When the BES 
option is specified, the CALL option 
is automatically set. 

Qhhk 

NOCALL (NCAL) 

indicates whether or not an automatic 
search of the SYSLIB data set is to be 
made. if the SYSLIB DD statement is 
not used in the input deck, this 
option is ignored. The NOCALL option 
causes an automatic MORES. 



If an execution- time parameter field 
is passed to a program, a load of the 
library subroutine ILBOPRM will be issued. 
If this subroutine is not available to the 
loader, an 806 abend may occur. One way 
to circumvent this problem is to place 
an INCLUDE SYSLIB (ILBOPRM) statement in 
the link edit SYSLIN data stream, which 
would link this subroutine into the load 
data set. 

User Parameters 

The programmer can code any parameters 
he wishes to pass to a main COBOL 
program. For information on how to 
access such parameters, see the "USING 
option" as described in IBM VS COBOL 
for os/ys. 



LET 

NOLET 

indicates whether or not the loader 
will try to execute the object program 
when a severity level 2 error 
condition is found. 

SI2J£iOOK 

SIZE=size 

specifies the size, in bytes, of 
dynamic main storage that can be used 
by the loader. This storage must be 
large enough to accommodate the object 
program. 

EP-narae 

specifies the external name to be 
assigned as the entry point of the 
loaded program. 

PRINT 

NOPRINT 

indicates whether or not diagnostic 
messages are to be produced on the 
SYSLOOT data set. 

The format of the PARM parameter is 
illustrated in Figure 8. The default 
options, indicated by an underscore, can be 
changed at system generation with the 
LOADEE macro instruction. 



Options for Execution 



These options are specified through the 
PARM parameter, as illustrated in Figure 8, 
Note that a slash must immediately precede 
the first COBOL-defined option coded. (If 
user parameters themselves are to include 
a slash or slashes, then an additional, 
trailing slash must be added to demark the 
user parameters' end. All data following 
the last slash is considered to be COBOL 
system parameter information, and will 
not be passed to the program.) 



FLOW[=nn] 

If the FLOW option is specified at 
compile time for a trace of procedure 
names, at execution time a value for 
an may be specified that overrides any 
value set at compile time. If FLOW is 
requested at compile time with no 
value for nn, a value should be 
specified at execution time. A 
default of 99 is assumed for nn if it 
is not specified at either step and 
FLOW is in effect; otherwise, nn is as 
previously specified. 

The FLOW trace may be suppressed at 
execution time by specifying NOFLOW. 
FLOW cannot be specified as an option 
for execution if it is not specified 
at compile time or if NOFLOW is in 
effect by default. See the sections 
"Debugging Facilities" and "Options 
for the Compiler" for additional 
information. 

DEBUG 

NODEBUG 

DEBUG indicates that USE FOB DEBUGGING 
declarative procedures are in the 
program and should in fact be 
activated during this execution. 
NODEBUG indicates that even though 
such declarative procedures were 
included in the program, they are not 
desired and their execution is to be 
suppressed. (Note that this DEBUG 
switch has meaning only if the source 
program was compiled with the WITH 
DEBUGGING MODE clause.) 

UPSI (nnnnnnnn) 

assigns values (either zero or one) to 
the eight switches UPSI-0, UPSI-1, 
UPSI-2, ... UPSI-7. <The default 
values are zeros.) These values are 
then available in the COBOL program 
through the condition names associated 
with them in the SPECIfti-NAMES 
paragraph. 
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AIXBLD 

NOAIXBLD 

for VSAM KSDS ana RRDS data sets, 
AIXBLD indicates that COBOL should 
invoke Access Method Services to 
complete the file and index definition 
procedures. NOAIXBLD indicates that 
the user has already performed such 
definitions himself ahead of time, and 
has no need for this service. 



In general, better performance is 
obtained if the user provides such 
definitions himself (NOAIXBLD) . If 
AIXBLD is specified, substantial 
amounts of additional storage are 
reguired for COBOL execution {the 
exact amount depending on specific 
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system configuration) . Also, a 
SYSPRINT DD card is necessary for any 
Access Method Services messages that 
may be produced. 



For more detail, see "Dynamic 
Invocation of Access Method services 
for KSDS and RRDS Output Data sets" in 
the section "VSAM File Processing." 

QUEUE<value-list) 

specifies a gueue-naae structure (in 
value-list) which is the structure 
that will cause this program to be 
scheduled for execution. For more 
detail, see "Communications Job 
Scheduling" in the section "Using the 
Communications Feature." 



Requesting Restart for a Job S te p (RP) 



The restart facilities can be used in 
order to minimize the time lost in 
reprocessing a job that abnormally 
terminates. These facilities permit the 
automatic restart of jobs that were 
abnormally terminated during execution. 

The programmer uses this parameter to 
tell the operating system: (1) whether or 
not to take checkpoints during execution of 
a program, and (2) whether or not to 
restart a program that has been 
interrupted. 

A checkpoint is taken by periodically 
recording the contents of storage and 
registers during execution of a program. 
The RERUN clause in the COBOL language 
facilitates taking checkpoint readings. 
Checkpoints are recorded onto a checkpoint 
data set. 

Execution of a job can be automatically 
restarted at the beginning of a job step 
that abnormally terminated (step restart) 
or within the step (checkpoint restart). 
In order for checkpoint restart to occur, a 
checkpoint must have been taken in the 
processing program prior to abnormal 
termination. The RD parameter specifies 
that step restart can occur or that the 
action of the CHKPT macro instruction is to 
be suppressed. 

To reguest that step restart be 
permitted or to request that the action of 
the CHKPT macro instruction be suppressed 
in a particular step, code the keyword 
parameter in the operand field of the EXEC 
statement. 



RD= request 



Replace the word "request" with: 

R — to permit automatic step restart. 
The programmer must specify at 
least one RERUN clause in order 
to take checkpoints. 

NC — to suppress the action of the 
CHKPT macro instruction and to 
prevent automatic restart. No 
checkpoints are taken; no RERUN 
clause in the COBOL program is 
necessary. 

NR — to request that the CHKPT macro 
instruction be allowed to 
establish a checkpoint , but to 
prevent automatic restart. The 
programmer must specify at least 
one RERUN clause in order to take 
checkpoints. 

RNC — to permit step restart and to 

suppress the action of the CHKPT 
macro instruction. No 
checkpoints are taken; no RERUN 
clause in the COBOL program is 
necessary. 



Each request is described in greater detail 
in the following paragraphs. 



RD=R: If the processing programs used by 
this step do not include a RERUN statement, 
RD=R allows execution to be resumed at the 
beginning of this step if it abnormally 
terminates. If any of these programs do 
include one or more CHKPT macro 
instructions (through the use of the RERUN 
clause) , step restart can occur if this 
step abnormally terminates before execution 
of a CHKPT macro instruction; thereafter, 
checkpoint restart can occur. 



RD=NC or RD=RNC: RD=NC or RD=RNC should be 
specified to suppress the action of all 
CHKPT macro instructions included in the 
programs used by this step. When RD=NC is 
specified, neither step restart nor 
checkpoint restart can occur. When RD=RNC 
is specified, step restart can occur. 



RD=NR : RD=NR permits a CHKPT macro 
instruction to establish a checkpoint, bat 
does not permit automatic restarts. 
However, a resubmitted job could have 
execution start at a specific checkpoint. 

Before automatic step restart occurs, 
all data sets in the restart step with a 
status of OLD or MOD, and all data sets 
being passed to steps following the restart 
step, are kept. All data sets in the 
restart step with a status of MEtf are 
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deleted. Before automatic checkpoint 
restart occurs, all data sets currently in 
use by the job are kept. 

If the RD parameter is omitted and no 
CHKPT macro instructions are executed, 
automatic restart cannot occur. If the RD 
parameter is omitted but one or more CHKPT 
macro instructions are executed, automatic 
checkpoint restart can occur. 

Nojb n es; 

• If the RD parameter is specified on the 
JOB statement, HD parameters on the 
job's EXEC statements are ignored. 

• Restart can occur only if MSGLEVEL=1 is 
coded on the JOB statement. 

• If step restart is requested for this 
step, assign the step a unique step 
name. 

• When this job step uses a cataloged 
procedure, make restart request for a 
single procedure step by including, as 
part of the RD parameter, the procedure 
stepname, i.e., RD.procstepname. This 
specification overrides the RD 
parameter in the named procedure step 
if one is present. Code as many 
parameters of this form as there are 
steps in the cataloged procedure. 

• To specify a restart request for an 
entire cataloged procedure, code the RD 
parameter without a procedure stepname. 
This specification overrides all RD 
parameters in the procedure if any are 
present. 

• If no RERUN clause is specified in the 
user*s program, no checkpoints are 
written, regardless of the disposition 
of the RD parameter. 

Reference: 

• For detailed information on the 
checkpoint/restart facilities, see the 
publication Og/Yg Checkpoint /Restart. 



step, code the keyword parameter in the 
operand field of the EXEC statement. 



DPRTY=(value 1, value 2) 



Both «v 
replaced w 
"Value 1« 
value. "V 
represents 
higher nura 
A default 
number is 
value of 1 
assigned t 

Notes: 



alue 1" and "value 2" should be 
ith a number from through 15. 
represents an internal priority 
alue 2" added to "value 1" 

the dispatching priority. The 
bers represent higher priorities, 
value of is assumed if no 
assigned to "value 1." A default 
1 is assumed if no number is 
o "value 2." 



• Whenever possible, avoid assigning a 
number of 15 to "value 1." This number 
is used for certain system tasks. 

• If "value 1" is omitted, the comma must 
be coded before "value 2" to indicate 
the absence of "value 1," e.g., 
DPRTY={, 14) . 

• If "value 2" is omitted, the 
parentheses need not be coded, e.g., 
DPRTY=12. 

• When the step uses a cataloged 
procedure, a dispatching priority can 
be assigned to a single procedure step 
by including the procedure step name in 
the DPRTY parameter, i.e., 

DPRTY. procstepname= {value 1, value 2). 
This parameter may be used for each 
step in the cataloged procedure. 

• To assign a single dispatching priority 
to an entire cataloged procedure, code 
the DPRTY parameter without a procedure 
step name. This specification 
overrides all DPRTY para meters in the 
procedure if there are any. 



Job step Time Limits (TIME) 



Prio rity Scheduling EXEC Par ame ters 



Establis hing a Dispa tchi n g Priority f DPRTY ) 
(0S/VS2 only) 

The DPRTY parameter allows the 
programmer to assign to a job step, a 
dispatching priority different from the 
priority of the job. The dispatching 
priority determines in what sequence tasks 
use main storage and computing time. To 
assign a dispatching priority to a job 



To assign a limit to the computing time 
used by a single job step, a cataloged 
procedure, or a cataloged procedure step, 
code the keyword parameter in the operand 
field of the EXEC statement. 



TIHE= (minutes, seconds) 



Such an assignment is useful in a 
multiprogramming environment where more 
than one job has access to the computing 
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system. Minutes and seconds represent the 
maximum number of minutes and seconds 
allotted for execution of the job step. 

Notes: 

• If the job step requires use of the 
system for 24 hours (1440 minutes) or 
longer, the programmer should specify. 
TTHE=1440. Using this number 
suppresses timing. The number of 
seconds cannot exceed 59. 

• If the time limit is given in minutes 
only, the parentheses need not be 
coded; e.g., TIME=5. 

• If the time limit is given in seconds, 
the comma must be coded to indicate the 
absence of minutes; e.g., TIME=(,45). 



♦ When the job step uses 
procedure, a time limi 
procedure step can be 
the keyword TIME with 
step name; i.e., TIME, 
(minutes, seconds) . Th 
overrides the TIME par 
named procedure step i 
As many parameters of 
coded as there are ste 
cataloged procedure. 



a cataloged 
t for a single 
set by qualifying 
the procedure 
procstep= 
is specification 
ameter in the 
f one is present, 
this form can be 
ps in the 



• To set a time limit for an entire 
procedure, the TIME keyword is left 
unqualified. This specification 
overrides all TIME parameters in the 
procedure if any are present. 

» If this parameter is omitted, the 
standard job step time limit is 
assigned. 



To specify a region size, code the 
keyword parameter in the operand field of 
the EXEC statement. 



REGION=<nnnnnK) 



To request the maximum amount of main 
storage required by the job, replace the 
term "nnnnn" with the maximum number of 
contiguous 1024-byte areas allocated to the 
job step, e.g., REGION=52R. This number 
can range from 1 to 5 digits but must not 
exceed 16383. 

If the REGION parameter is omitted or if 
a region size smaller than the default 
region size is requested, it is assumed 
that the default value is that established 
by the input reader procedure. 



Uotes: 



Region sizes for each job step can be 
coded by specifying the REGION 
parameter in the EXEC statement for 
each job step. However, if a REGION 
parameter is present in the JOB 
statement, it overrides REGION 
parameters in EXEC statements. 

For information on storage requirements 
to be considered when specifying a 
region size, see the appropriate 
Storage Estimates publication. 



specifying Address S pace (A DDRSPO 



Specifying Main Stor age Re qu irements for a 
Job Step, JREGIQN) 



The REGION parame 
programmer to specif 
storage region to be 
associated job step, 
specifies the maximu 
storage to be alloca 
amount must include 
components required 
that are not residen 



ter permits the 
y the size of the main 
allocated to the 
The REGION parameter 
m amount of main 
ted to the job. This 
the size of those 
by the user's program 
t in main storage. 



To take advantage of the storage 
facilities offered by OS/VS1 and OS/VS2, 
always specify ADDRSPC=VIRT. 



ADDRSPC= 



\realj 



Note that the compiler and its object code, 
including library subroutines, can run 
VIRTUAL, and should be run that way unless 
a non-COBOL program in the partition 
requires the REAL option. 



The REGION parameter is used in 
conjunction with the ADDRSPC parameter to 
determine the total amount of main storage 
available to a program and to either allow 
or disallow paging. 

Note; The REGION parameter has different 
meanings for OS/VS 1 and OS/VS2. See the 
publication OS/VS JC L serv ices for detailed 
information. 



aS_SXATEM£NT 



The data definition (DD) statement 
identifies each data set that is to be used 
in a job step, and it furnishes information 
about the data set. The DD statement 
specifies input/output facilities required 
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for using the data set; it also establishes Paraneters used most frequently for 

a logical relationship between the data set COBOL programs are discussed in detail, 

and input/output references in the program The other parameters (e.g., SEP and AFF) 

named in the EXEC statement for the job are mentioned briefly. For further 

step. information, see the publication QS^VS_JCL 

Reference . 
Figure 9 is a general format of the DD 
statement. 
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me ) » 

step, ddname) 



1 Operation 
_l 

| DD 



Operand 



(see below and next page) 



J Operand* 
I 



Positional Para meters 3 

[(DATA/ [ ,DLM=xx3j 



[DUMMY] 



[DYHftH]* 



K eywo rd Par ameter s s * 
[DDNAME=ddname] 



12 




dsname 

dsname (element) 

♦.ddname 

♦.stepname. ddname 

♦ . stepname. procstep. ddname/ 

Sfiname 

SSname (element) 

NULLFILE 



[QNAME=processname]»* 
~"J>-CB= (list of attributes) 



DCB=( 



dsname 

♦.ddname 

♦.stepname. ddname 

♦ .stepname. procstep. ddname. 



[ , sub par a meter- list]) 



list)*] >i 



SEP= (subparameter 
[AFF=ddname 
[COPIES=nnn] 
[OUTLIM=number] 

(BT\ 
[ TEEM^TSQ 

P ositional gubpar a me tgys. 



SexwQxd_Subparaneters 



UNIT= (name[ ,[n/P][, DEFER ]J[ ,SEP= (list of up to 8 ddnames) ]) 

ONIT=(AFF=ddnamej 

TJCS= (character set code ,FOLD [,VEHIFY])] 



9 11 13 



I See notes at end of figure. 

L_ , 



Figure 9. The DD Statement (Part 1 of 3) 
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I operand* 



(TRK 
SPACE=( <CYL 

(average- record-length 



Positional S ub pa ra me te rs 

r {primary-quantityf , secondary-quantity ], 



[directory- or index-quantity ]) [ ,RLSE] 



, MXLG 

,ALX 

,CONTIG 



[ , ROUND ]) 



SPACE= (ABSTR, {quantity ,beginning-address[ , directory- or index-quantity]) ) 
(CYL 



SPLIT=(n, 



[ay er age- record-length 



, {primary-quantity£ secondary- quantity ]) ) 



(trk ) 

S0BALLOC={ <CYL \ (primary-quantity[ ^secondary-quantity ] 

I average-record- lengthj 

! ddname ) 

step name. ddname > ) 

stepname. procstep. ddname) 
(VOLUME) 
(VOL J ={[ PRIVATE ],[ RETAIN ],£ volume sequence number },[ volume count ■][,] 



H 



SER= (volume-serial-number[ volume-serial-number ]* °- - . ) 

(dsname 
BEF= 1*. ddname 

S*. stepname. ddname 

'*. stepname. procstep. ddname ! 



See notes at end of figure 



Figure 9. The DD Statement (Part 2 of 3) 
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J operand* 

I 

Keyword Su bpar ameters 

LABEL= ([ data-set-sequence-number ], 



NL 

SL 

NSL 

SUL 

LTH 

BLP 

AUL 

AL 



, PASSWORD 
, NOPWREAD 



.IN " 

, OUT 



,EXPDT=yyddd 
,RETPD=XXXX 



DISP={ 



III 
OLD 
SHH 
MOD 



; DELETE ' 
,KEEP 
,PASS 
,CATLG 
_,UNCATLG 



|",DELETE 1 




,KEEP 




,CATLG 


) 


,UNCATLG 


■. 




_ 



[SYSOUT= (classname[ , program-name ][ , form-no. ])] 

,ALIGiq 
VERIFY J 



[FCB= (image-id |~ ,ALIG1T[) 



[AMP= (subparameters) is] 



*The name field must be blank when concatenating data sets. 

2A11 parameters are optional to allow a programmer flexibility in the use of the DD 

statement; however, a DD statement with a blank operand field is meaningless. 
3 If the positional parameter is specified, keyword parameters other than DCB cannot be 

specified. 
♦For 0S/VS2 only. 

sif subparameter-list consists of only one subparameter and no leading comma 
(indicating the omission of a positional subparameter) is required, the delimiting 
parentheses may be omitted. 
*I f subparameter-list is omitted, the entire parameter must be omitted. 
7 See "user-Defined Files" for the applicable subparameters. 
ssee the publication Q S/ VS jci Ref erence . 

9 If only name is specified, the delimiting parentheses may be omitted. 
i°If only one volume-serial-number is specified, the delimiting parentheses may be 

omitted. 
**The SEP and AFF parameters should not be confused with the SEP and AFF subparameters 

of the UNIT parameter. 
» 2 The value specified may contain special characters if the value is enclosed in 

apostrophes. If the only special character used is the hyphen, the value need not be 
enclosed in apostrophes. If DSNAME is a qualified name, it may contain periods 
without being enclosed in apostrophes. 
l3 The unit address may contain a slash, and the unit type number may contain a hyphen, 

without being enclosed in apostrophes, e.g., GNIT=293/5,UNIT=2400~2. 
i*The QRAME= parameter is used in COBOL teleprocessing and must be the name of a TCAM 

destination queue. 
t^This parameter is for use with VSAH only. The subparameters are described in the 
chapter "VSAM File Processing." 

Figure 9. The DD Statement (Part 3 of 3) 



Job Control Procedures 55 



Na»e_£ield 

ddname (Identifying the DD Statement) 
is used: 

• To identify data sets defined by 
this DD statement to the compiler or 
linkage editor (see "Compiler Data 
Set Requirements" and "Linkage 
Editor Data Set Requirements") , 

• To relate the data sets defined in 
this DD statement to a file 
described in a COBOL source program 
(see "User- Defined Files"). 

• to identify this DD statement to 
other control statements in the 
input stream. 

pr oc st e p. d dn am e 

is used to alter or add DD statements 
in cataloged procedures. The step in 
the cataloged procedure is identified 
by procstep. The ddname identifies 
either one of the following: 

• ft DD statement in the cataloged 
procedure that is to be modified by 
the DD statement in the input 
stream. 

• A DD statement that is to be added 
to the DD statement in the procedure 
step. 



* m Parameter (Defining Data in an Input 

Stre am ) 

indicates that data immediately 
follows this DD statement in the input 
stream. This parameter is used to 
specify a source deck or data in the 
input stream. The data cannot contain 
// or /* in the first two character 
positions of any record unless the DLM 
parameter is used. If (while scanning 
JCL) the system encounters a card that 
does not begin with //, it logically 
inserts a //SYSIN DD * card before it. 
The SYSIN data set thus created is 
delimited by the next /* or // job 
control card encountered. 

DA TA Par a meter (Def ining Data in an Input 

Stream ) 

also indicates a JCL deck or data in 
the input stream. The end of the data 
set must be indicated by a delimiter 
statement. The data cannot contain /* 
in the first two characters of any 
recprd unless the DLM parameter is 
used. The DD DATA statement must be 
the last DD statement of the job step. 
// may appear in the first and second 
positions in the record, for example, 
when the data consists of control 
statements of a procedure that is to 
be cataloged. 



PLM Parameter (Changing Data Delimiter for 

Input Strea m ) 

specifies the delimiter to be used 
instead of /* or // to terminate data 
defined in the input stream. 
Assigning a different delimiter allows 
the standard delimiter (/* or //) to 
be used as data in the input stream. 
The DLM parameter has meaning only on 
DD* and DD DATA statements. The data 
must be terminated with the characters 
assigned in the DLM parameter. 



DUMMY Parameter (Byp a ssing Device 
Allocation and input Qperg : tions,on - _th j e,.Data 
set) 

allows a program to attempt I/O 
operations on a data set during 
execution without the operating 
system's performing actual operations 
on the data set. (Programs compiled 
with the LANGLVL(2) option can specify 
the COBOL source statement SELECT 
OPTIONAL to obtain this ability and 
thus avoid supplying a dummy DD 
statement.) The DOMMY parameter is 
valid only for COBOL input sequential 
data sets. No device allocation, 
external storage allocation, or 
cataloging takes place for dummy data 
sets. When the DUMMY parameter is 
specified, a read request to an 
"opened" file results in an end of 
data set exit. 

For a VSAM data set, if DUMMY is 
specified, an attempt to read results 
in an end-of-data condition. 
AMP=*AMORG* must be specified if DUMMY 
is specified; see "VSAM-only JCL 
Parameter" in the chapter "VSAM File 
processing. " 

Note: Compiler work files (including 
SYSUT5 and SYSUT6) cannot be described 
as DD DUMMY. 

Data in the input stream is temporarily 
transferred to a direct-access device for 
later high-speed retrieval. Normally, the 
system stores it in a format that is not 
under control of the programmer. However, 
in some situations the programmer may be 
able to assign his own values through use 
of the BLKSIZE subparameter of the DCB 
parameter. He may also indicate the number 
of buffers to be assigned to transmitting 
the data, through use of the BUFNG 
parameter. For example, he may assign the 
following: 

DCB= (BLKSI2E=800 , BUFN0=2) 

In YS1 and VS2 Release 2 and later, maximum 
performance is obtained for SYSIN and 
SYSOUT data sets when BLKSIZE=80 and 
BUFNO=1 are used. If not supplied by the 
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problem program, it can be supplied by the 
DCB parameter on the DD statement. If 
omitted from both sources, the defaults are 
BLKSIZE=80 and BUFN0=2. 



DYNA M , Parameter {Reservi ng S pace under 



0S/VS2 with TSO) 

specifies that space 
in internal tables so 
requirements that ari 
terminal session can 
This allows deferred 
data set until it is 
LOGON processing for 
or external storage a 
data set defined by a 
statement. When a da 
reguired, the actual 
external storage for 
then allocated. see 
OS/VS2 TSO Guide, Ord 
for further informati 



is to be reserved 

that data set 
se during a TSO 
be satisfied, 
definition of a 
reguired. During 
TSO, no devices 
re allocated to a 

DD DYNAM 
ta set is 
device and 
the data set is 
the publication 
er No. GC28-0644, 
on. 



Note: No other parameter can be 
specified on a DD statement where 
DYNAM is specified. 



DDNAME Parameter { P o s tponing the p ef initio n 

of a Dat a Set ) 

defines a pseudo data set that will 
assume the characteristics of a real 
data set if a subsequent DD statement 
of the step is labeled with the 
specified ddname. When the DDNAHE 
parameter is specified, it must be the 
first parameter in the operand. All 
other parameters, except the DCB 
sub para meters BLKSIZE, BUFNO, and 
DIAGNS, are ignored and should be 
omitted when the DDNAME parameter 
appears (see "Using the Cataloged 
Procedures") . 

The ddname specifies a DD statement 
that, if present, supplies the 
attributes of the data set. If it is 
not present, the statement is ignored. 



DSNAME Parameter {Identifying the Data Set) 
allows the programmer to specify the 
name of the data set to be created or 
to refer to a previously created data 
set. Various types of names can be 
specified (see "Using the DD 
Statement" for a discussion of the 
various names) as follows: 

* Fully .qualified names: For data 
sets to be retrieved from or stored 
in the system catalog. 

* Gen erati on data group names: For an 
entire generation data group, or any 
single generation thereof. 



* Simple name s: For data sets that 
are not cataloged. 

* Ref erence n a me s: For data sets 
whose names are given in the DSNAHE 
parameter of another DD statement in 
the same job. 

* Temporary^. names; For temporary data 
sets that are to be named for the 
duration of one job only. 

If the DSNAME parameter is omitted, 
the operating system assigns a unique 
name to the data set. (This parameter 
should be supplied for all except 
temporary data sets to allow future 
referencing of the data set.) DSNAME 
may be coded DSN. 

DSNAME Subparameters 

dsname 

specifies the fully qualified 
name of a data set. This is the 
name under which the data set can 
be cataloged or otherwise 
identified on the volume. 



dsname {element) 

specifies a particular 
generated data group, 
partitioned data set, 
indexed data set. To 
generation of a genera 
the element is a zero 
integer. To indicate 
partitioned data set, 
name. To indicate an 
indexed data set, the 
PRIME, OVFLOW, or INDE 
the DD Statement" for 
about generation data 
examples of partitione 



generation of a 
a member of a 
or an area of an 
indicate a 
ted data group, 
or a signed 
a member of a 
the element is a 
area of an 
element is 
X {see "Using 
information 
groups and 
d data sets) . 



*. ddname 

indicates that the DSNAME parameter 
{only) is to be copied from a 
preceding DD statement in the current 
job step. 

* . st epname . ddna me 

indicates that the DSNAME parameter 
(only) is to be copied from the DD 
statement, ddname, that occurred in a 
previous step, stepname, in the 
current job. If this form of the 
subparameter appears in a DD statement 
of a cataloged procedure, stepname 
refers to a previous step of the 
procedure, or, if no such step is 
found, to a previous step of the 
current job. 

*. stepname. procstep. ddname 

indicates that the DSNAME parameter 
(only) is to be copied from a DD 
statement in a cataloged procedure. 
The EXEC statement that called for 
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execution of the procedure, as well as 
the step and DD statement of the 
procedure, oust be identified. 

&&naae 

allows the programmer to supply a 
temporary name for a data set that is 
to be deleted at the end of the job. 
The operating system substitutes a 
unique symbol for this sub parameter. 
The programmer can use the temporary 
name in other steps to refer to the 
data set. The same symbol is 
substituted for each recurrence of 
this name within the job. Upon 
completion of the job, the name is 
dissociated from the data set. The 
same temporary name can be used in 
other jobs without ambiguity. 

S&na me (element) 

allows the programmer to supply a name 
for a member of a temporary 
partitioned data set that will be 
deleted at the end of the step. 

NULL PILE 

serves the same function as the DUMMY 
parameter (described above) . 



QNAME Parameter (Defining the Data to be 

Acc essed bv TCAH) 

specifies the name of a TPROCESS macro 
that defines a destination queue for 
messages that are to be processed by 
an application program and creates a 
process entry for the queue in the 
Terminal Table (see the section 
"Defining Terminal and Line Control 
Areas" in the chapter entitled "Using 
the Teleprocessing Feature"). 

jiote: The DCB parameter is the only 
parameter that can be coded on a DD 
statement with the QNAME parameter. 
The only operands that may be 
specified as subparameters are 
BLKSTZE, BUFL, LRECL, OPTCD, and 
RECFM. 



DC B Parameter ( Des cr ibing th e A t tributes of 

the Dat a S et) 

allows the programmer to specify at 
execution time, rather than at 
compilation time, information for 
completing the data control block 
associated with the data set (see 
"Execution Time Data Set Requirements" 
and "Additional File Processing 
Information" for further information 
about the data control block and DCB 
subparameters) . 

The first subparameter of this 
parameter may be used to copy DCB 
attributes from the data set label of 



a cataloged data set or from a 
preceding DD statement (see the 
publication OS /ys JCL Re ference for 
detailed information about the DCB 
subparameter) . 



SEP and AFF Parameters (Op timizing Channel 

"sage). 

allow the programmer to optimize the 
use of channels among groups of data 
sets. SEP indicates channel 
separation and AFF indicates channel 
affinity. SEP and AFF are ignored for 
any data sets that have been allocated 
devices by the automatic volume 
recognition (AVR) option. 

If neither parameter is supplied, any 
available channel, consistent with the 
UNIT parameter requirement, is 
assigned. The affinity parameter 
groups two or more data sets so that 
they can be separated from another 
data set requesting channel 
separation. For indexed sequential 
data sets these parameters are written 
in the same way as those for any data 
set. For VSAM data sets, these 
parameters should not be used if the 
data and its index reside on unlike 
devices. They can be used in 
succeeding DD statements to refer to 
the first DD statement defining an 
indexed seguential data set. However, 
the second and third DD statements 
cannot request separation from or 
affinity to one another because they 
are unnamed. Thus, to establish 
channel separation and affinity for 
all of the areas, the name 
subparameter of the UNIT parameter 
must be used to request specific 
devices on specific channels. 



UNIT P a rameter (Requesting a Unit) 

specifies the quantity and types of 
input/output devices to be allocated 
for use by the data set. 

If the UNIT parameter is not specified 
in the current DD statement, there are 
several ways in which the unit 
information may be inferred by the 
system: 

• If the current data set has already 
been created and it is either being 
passed to the current step, or if it 
has been cataloged, any unit name 
specified in this DD statement is 
ignored. 

• If the REF subparameter of the 
VOLUME parameter is specified, the 
current data set is given affinity 
with the data set referred to; that 



58 



data set's defining DD statement 
provides the unit information. 



installation at system generation 
time. 



• If the current data set is to 
operate in the split cylinder mode 
with a previously defined data set, 
it will reside on the unit specified 
in the DD statement for the previous 
data set. 

• If the current data set is to use 
space suhallocated from that 
assigned to a previously defined 
data set, it will reside on the same 
unit as the data set from which the 
space is obtained. 

• If the current data set is assigned 
to the standard output class (SYSO0T 
is specified) , it is written on the 
unit specified by the operator for 
class A. 

If the current data set is in the input 
stream {defined by a DD * or DD DATA 
statement) , the DD statement defining the 
data set should not contain a UNIT 
parameter. 

If this parameter specifies a mass 
storage device for a data set being 
created, it is also necessary to reserve 
the space the data set will occupy, using 
another parameter of the DD statement. For 
VSAM data sets, the AFF and SEP 
subparameters should not be used if the 
data and its index reside on unlike 
devices. Depending on the way in which the 
space will be used, the SPACE, SPLIT, or 
SOBALLOC parameter can be specified. These 
parameters are discussed under individual 
headings. 

If the UNIT parameter specifies a tape 
device, no SPACE, SPLIT, or SOBALLOC 
parameters are required. 

The UNIT parameter must be specified if 
VOLUME=SEE is specified in the DD 
statement. 

UNIT Su bparameters: 

name 

specifies the name of an input/output 
device, a device class name, or any 
meaningful combination of input/output 
devices specified by an installation. 
(Mass storage devices and magnetic 
tape devices can be combined. No 
other device type combination is 
allowed.) Names and device classes 
are defined at system generation time. 
The device class names that are 
required for IBM cataloged procedures 
and are normally used by most 
installations are shown in Figure 10. 
These names can be specified by the 



The block size specified in the source 
program (in the BLOCK CONTAINS clause 
or in the record description) must not 
exceed the maximum block size 
permitted for the device. For 
example, the maximum block size for 
the IBB 2314 is 7294 characters, and 
the maximum block size for the IBM 
2400 series is 32,760 characters. 



Note: when device-independence is 
specified by use of UT as the device 
class in the ASSIGN statement in the 
Environment Division, the device 
chosen by the system will be dependent 
on the DD statement. Therefore, if 
the user's installation has both an 
IBM 2314 and an IBM 3330 that may be 
used as utility devices, the user 
should write 

BLOCK CONTAINS 7294 CHARACTERS 

(or any number smaller than 7294) to 
ensure that the block can be contained 
on one track. 



specifies the number of devices to be 
allocated to the data set. If this 
parameter is omitted, 1 is assumed. 



specifies parallel mount. 

DEFER 

indicates deferred mounting. Deferred 
iaounting cannot be specified for a new 
output data set on a mass storage 
device or for an ISAM data set. 
For VSAM data sets, it indicates that 
the volumes are not to be mounted 
until access method services requires 
them. 

SEP=(list of up to eight ddnames) 
specifies unit separation. 

AFF=ddname 

specifies unit affinity. 



J j j , 

{Class NameJ Class Functionsi Device Type 
j 

ISYSSQ 



1 writing 
J reading 



\ mass storage I 
J magnetic tape \ 



JSYSDA 
I 



| writing 
treading 



Jmass storage 
\ 

-J : 



Figure 10. Device class Names Required for 
IBM-Supplied Cataloged 
Procedures 



Job Control Procedures 59 



C OPIES P arameter (Requesting Add itional 

Data Set Copies ) 

is specified when more than one copy 
of the output data sets is desired. 
It can be specified only with the 
SYSOUT parameter on the same DD 
statement. The maximum number of 
copies that can be requested is 255. 
For further information on the use of 
the COPIES parameter, see the 
publication OS/ VS JCL Serv ices. 



OUTL IM P a rameter ( Specifying 

Limit) 

is specified, for OS/VS 
limit the number of log 
be included in the outp 
being routed through th 
stream. For 0S/YS2, O0 
ignored. When the litni 
an exit provided by the 
Management Facilities o 
to a user-supplied rout 
determines whether to c 
or increase the limit, 
routine is not supplied 
canceled. The largest 
be specified is 1677721 



Output Record 



1 only, to 

ical records to 

ut data set 

e output 

TLIM is 

t is reached. 

System 
ption is taken 
ine that 
an eel the job 

If the exit 
, the job is 
number that can 
5. 



The OUTLIM para 
if the system M 
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11 Hfi Parameter ( Notify System of a Special 

Device) 



specifies different 
OS/VS 1 and 0S/VS2. 
parameter notifies 
presence of an 8TAH 
Access Method) devi 
(Remote Entry Servi 
TSO, the TEEM paraa 
system that a data 
or going to a time 



information for 
For VS1, the TERM 
the system to the 
(Remote Terminal 
ce used with RES 
ces) . For VS2 with 
eter notifies the 
set is coming from 
sharing terminal. 



See the publication OS/VS 1 RES, System 
Programmer's Guide, Order 
No. GC2 8-6878, ~f or detailed 
information on Remote Entry Services. 



TERM Subparamete r: 

It 

indicates that a remote unit record 
device is in use for RTAM and that the 
usual allocation processing is to be 
bypassed. RT can only be specified on 



TS 



a DD statement for a job that is a 
system task. RT should not be 
specified on DD*, DD DATA and SYSOUT 
DD statements. 



indicates to the system that the input 
or output data being defined is coming 
from or going to a time sharing 
terminal. If TSO is not in use, the 
DD statement containing the TERM 
parameter is treated as a DD DUMMY 
statement. Only the DCB parameter can 
be specified with TERM=TS; any other 
parameters specified on the same DD 
statement are ignored. 



UCS Para meter (Specifying Character Set/for 

a 1403 or 3211 Printer) 

describes the character set to be used 
for printing an output data set on a 
1403 or 3211 printer. In order to use 
a particular special character set, an 
image of the character set must be 
contained in 5YS1.IMAGEL.IB, and the 
chain or train corresponding to the 
character set must be available for 
use. The OCS parameter, the DDNAME 
parameter, and the DCB subpararaeters 
RKP, CYLOFL, and INTVL, are mutually 
exclusive. For further information on 
the UCS parameter, see the publication 
OS/VS System Programming Library; 
Data Ma nag e men t. 



UCS Subparameters : 

character set code 

identifies the special character set 
to be used for printing the data set. 



FOLD 



specifies that the chain or train 
corresponding to the desired character 
set is to be loaded in the fold mode. 
The fold mode is described in the 
publication IBM 2821 Control Unit. 
Order No. GA2 4-3112. 



VERIFY 

specifies that the operator is to 
verify that the correct chain or train 
is mounted before the data set is 
printed. If the VERIFY subparameter 
is specified and the FOLD subparameter 
is not, a comma must precede VERIFY 
since FOLD is a positional 
subparameter and its absence must be 
indicated. 



60 



SPACE Pa rame te r (Al locating Mass Storage 
Sgace^ 

specifies space to 

mass storage volume 

has no meaning for 

data set is assigne 

that contains both 

devices and tape de 

be specified. For 

space is allocated 

method services. 



be allocated in a 
. Although SPACE 
tape volumes, if a 
d to a device class 
mass storage 
vices, SPACE should 
VSAM data sets, 
through access 



Two forms of the SPACE parameter may 
be used, with or without absolute 
track address (ABSTE) . The ABSTE 
parameter requests that allocation 
begin at a specific address. 



:e Subp arameters: 

ISTR 

K 

'L 

r erage-record-len 
specifies the u 
which storage i 
units may be tr 
cylinders (CYI) 
{aver age- record 
decimal number) 
ABSTE subparame 
allocated space 
specific track 
specified track 
to another data 
reallocated to 



gthj 

nit of measurement in 

s to be assigned. The 

acks (ABSTE or TRK) , 

, or records 

-length, expressed as a 

In addition, the 
ter indicates that the 

is to begin at a 
address. If the 
s are already allocated 

set, they will not be 
this data set. 



Note: For ISAM data sets, only the 
CYL or ABSTE subparameter is 
permitted, when an ISAM data set is 
defined by more than one DD statement, 
all must specify either CYL or ABSTR; 
if some statements contain CYL and 
others ABSTE, the job will be 
abnormally terminated. 



(primary-quantity[ , secondary-quantity] 

[, directory- or index-quantity]) 

specifies the amount of space to be 
allocated for the data set. The 
primary quantity indicates the number 
of records, tracks, or cylinders to be 
allocated when the job step begins. 
For ISAM data sets, this subparameter 
specifies the number of cylinders for 
the prime, overflow, or index area 
(see "Execution Time Data Set 
Requirements") . The secondary 
quantity indicates how much additional 
space is to be allocated each time 
previously allocated space is 
exhausted. This subparameter must no t 
be specified when defining an ISAM 
data set. If a secondary quantity is 
specified for a sequential data set, 
the program may receive control when 
additional space cannot be allocated 



to write a record, 
quantity is used w 
creating a partiti 
and it specifies t 
256-byte records t 
the directory of t 
specify the number 
allocated for an i 
within the prime a 
data set is being 
publication os/yjs 



The directory 
hen initially 
oned data set (PDS) , 
he number of 
o be reserved for 
he PDS. It can also 
of cylinders to be 
ndex area embedded 
rea when a new ISAM 
defined (see the 
JC L . Refe rence ) . 




The directory contains the name 
he relative position, within the 
set, for each member of a 
tioned data set. The name 
res eight bytes, the location 
bytes. Up to 62 additional bytes 
e used for additional 
mation. For a directory of a 
tioned data set that contains 
modules, the minimum directory 
rement for each member is 34 



ELSE 



indicates that all unused external 
storage assigned to this data set is 
to be released when processing of the 
data set is completed, 

'MXIG ) 
ALX \ 

[CONTIGJ 

qualifies the request for the space to 
be allocated to the data set. MXIG 
requests the largest single block of 
storage that is greater than or equal 
to the space requested in the primary 
quantity. ALX requests the allocation 
of additional tracks in the volume. 
The operating system will allocate 
tracks in up to five blocks of 
storage, each block equal to or 
greater than the primary quantity. 
CONTIG requests that the space 
indicated in the primary quantity be 
contiguous. 

If this subparameter is not 
specified, or if any option cannot be 
fulfilled, the operating system 
attempts to assign contiguous space. 
If there is not enough contiguous 
space, up to five noncontiguous areas 
are allocated. 

ROUND 

indicates that allocation of space for 
the specified number of records is to 
begin and end on a cylinder boundary. 
It can be used only when average 
record length is specified as the 
first subparameter. 

quantity 

specifies the number of tracks to be 
allocated. For an ISAM data set, this 
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quantity oust be equivalent to an 
integral number of cylinders; it 
specifies the space for the prise, 
overflow, or index area (see 
"Execution Time Data Set 
Requirements") . 

beginning address 

specifies the relative number of the 
track desired, where the first track 
of a volume is defined as 0. (Track ( 
cannot be requested.) The number is 
automatically converted to an address 
based on the particular device 
assigned. For an ISAM data set this 
number must indicate the beginning of 
a cylinder. 



directory quantity 

defines the number of 
to be allocated for t 
new partitioned data 
specifies the number 
allocated for an inde 
within the prime area 
indexed data set is b 
the latter case, the 
must be equivalent to 
number of cylinders { 
publication 0S./IS__JCL 



256-byte records 
he directory of a 
set. It also 
of tracks to be 
x area embedded 

when a new 
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number of tracks 

an integral 
see the 

Reference ) . 



SPLIT Parameter (Allocating Mass storage 
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Note: SPLIT should not be used a) 
when one of the data sets is an ISAM 
data set, or b) under VS2 Belease 2 or 
later. 



SPLI T Subpar ameters: 

n 

indicates the number of tracks per 
cylinder to be used for this data set 
if CYL is specified. If the average 
record length is specified, n is the 
percentage of the tracks per cylinder 
to be used for this data set. 

(CYL \ 

(average- record -length) 

indicates the units in which the space 
requirements are expressed in the next 
s ub pa ra me te r. The units aay be 
cylinders (CYL) or physical records 
(in which case the average record 



length in bytes is specified as a 
decimal number not exceeding 65,535). 
If the average record length is given, 
and the data set is defined to have a 
key, the key length must be given in 
the DCB paraneter of this DD 
statement. 



primary- quantity 

defines the number of cylinders or 
space for records to be allocated to 
the entire group of data sets. 



secondary- quantity 

defines the number of cylinders or 
space for records to be allocated each 
time the space allocated to any of the 
data sets in the group has been 
exhausted and more data is to be 
written. This quantity will not be 
s pi it . 



A group of 
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s q f BALLOC Parameter fAlloca 
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which contiguous 
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obtained through 
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The S0BAL10C 
be used to obtain 
a set, nor should 
Release 2 or 



Except for the subparameters 
described below, the subparameters in 
the SUB ALLOC parameter have the same 
meaning as those described in the 
SPACE parameter. 



SUBALLOC Subpa rameters: 

ddname 

indicates that space is to be 
suballocated from the data set defined 
by the DD statement, ddname, that 
appears in the current step. 
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stepname. ddname 

indicates that spac 
suballocated from t 
by the DD statement 
in a previous step, 
form of the subpara 
DD statement in a c 
stepname refers to 
the procedure, or i 
found, to a previou 
current job. 



e is to be 
he data set defined 
, ddname, occurring 
stepname. If this 
meter appears in a 
ataloged procedure, 
a previous step of 
f no such step is 
s step of the 



theUNIT parameter- Such a data set is 
deleted at the end of the job. 



The manner in which the programmer 
requests a volume can be considered 
specific or n onspecif ic. A specific 
reference is implied whenever a volume 
with a specific serial number is 
requested. Any one of the following 
conditions denotes a specific volume 
reference: 



stepname. procste p. ddname 

indicates that space is to be 
suballocated from a data set defined 
in a cataloged procedure. The first 
term identifies the step that called 
for execution of the procedure, the 
second identifies the procedure step, 
and the third identifies the DD 
statement that originally requested 
space. 



VOLUME (VOL) Parameter j Specif ying V olum e 
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Data sets can be classified as one 
of two types, t emporar y or 
nonte mporar y. A temporary data set 
exists only for the duration of the 
step that creates it. A nontemporary 
data set can exist after the job is 
completed. The programmer indicates 
that a data set is temporary by 
coding: 

• DSNAME=S&name 

• No DSNAME parameter 

• DISP= {NEW, DELETE) , either explicitly 
or implied, e.g., DISP= (, DELETE) 

• DSNAME=reference, referring to a DD 
statement that defines a temporary 
data set. 

All other data sets are considered 
nontemporary. If the programmer 
attempts to Keep or catalog a passed 
data set that was declared temporary, 
the system changes the disposition to 
PASS unless DEFER was specified in 



• The data set is cataloged or passed 
from an earlier job step. 

• VOLaME=SER is coded in the DD 
statement. 

• VOLUME=EEF is coded in the DD 
statement, referring to an earlier 
specific volume reference. 

All other types of volume references 
are nonspecific. (Nonspecific 
references can be made only for new 
data sets, in which case the system 
assigns a suitable volume.) 

The state of a volume determines 
when the volume will be demounted and 
what kinds of data sets can be 
assigned to it. 
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Permanently resident volumes are 
always mounted. The permanently 
resident characteristic applies 
automatically to: 

• All physically permanent volumes, 
such as 230 5 Fixed Head Storage. 

• The volume from which the system is 
loaded (the IPL volume) - 

• The volume containing the system 
data sets SYS1.LIMLIB, 

SYS1. P10CLIB, and job scheduler 
queue. 



Job Control Procedures 63 



• Other volumes can be designated as 
permanently resident in a special 
member of SYS1.PR0CLIB named 
PRESSES. 



Permanently resident volumes are 
always public. The reserved 
characteristic applies to volumes that 
remain mounted until the operator 
issues an UNLOAD command. They are 
reserved by a MOUNT command referring 
to the unit on which they are mounted 
or by a system parameter library 
entry. The removable characteristic 
applies to all volumes that are 
neither permanently resident nor 
reserved. Removable volumes do not 
have an allocation characteristic when 
they are not mounted. A reserved 
volume becomes removable after an 
UNLOAD command is issued for the unit 
on which it resides. 

The allocation characteristics, 
public, private, and storage, indicate 
the availability status of a volume 
for assignment by the system to 
temporary data sets, and, if the 
volume is removable, when it is to be 
demounted. A public volume is used 
primarily for temporary data sets and, 
if it is permanently resident, for 
frequently used data sets. It must be 
reguested by a specific volume 
reference if a data set is to be kept 
or cataloged on it. If a public 
volume is removable, it is demounted 
only when its unit is required by 
another volume. The programmer can 
change a public volume to private 
status by specifying VOLUME=PRIVATE. 
A priva te volume must be requested by 
a specific volume reference. A new 
data set can be assigned to a private 
volume by specifying VOLUME=PRIVATE. 
If the volume is reserved, it remains 
mounted until the operator issues an 
UNLOAD command for the unit on which 
it resides. If it is removable, it 
will be demounted after it is used, 
unless the programmer specifically 
reguested that it be retained 
(VOLUME=, RETAIN) or passed 
(DISP=,PASS) . Once a removable volume 
has been made private, it will 
ultimately be demounted. To use it as 
a public volume, it must be remounted. 
* storage volume is used as an 
extension of main storage, to keep or 
catalog nontemporary data sets having 
nonspecific volume requests. The 
programmer can assign the PRIVATE 
option to storage volumes. 

Figure 11 shows how mass storage 
volumes are assigned their mount and 
allocation characteristics. 
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Figure 11. Mass Storage Volume States 



Magnetic f*pe volumes: The volume 
state of a reel of magnetic tape is 
also determined by a combination of 
mount and allocation characteristics: 



Mount 

Charact eristics 

Reserved 

Removable 



Allocation 
Characteristics 
Private 
Scratch 



The reserved -scratch combination is 
not a valid volume state. Rese rved 
tape volumes assume their state when 
the operator issues a MOUNT command 
for the unit on which they reside. 
They remain mounted until the operator 
issues a corresponding UNLOAD command. 
Reserved tapes must be requested by a 
specific volume reference. 

A removable tape volume is assigned 
the private characteristic when one of 
the following occurs: 

• It is requested with a specific 
volume reference. 

• It is requested for allocation to a 
nontemporary data set. 

» The VOLUME parameter is coded with 
the PRIVATE option. 

A removable-private volume is 
demounted after its last use in the 
job step, unless the programmer 
requests that it be retained. 

All other tape volumes are assigned 
the r emovab le- scratch state. The tape 
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volumes remain mounted until their 
unit is required by another volume. 



Vplufle. Parameter Facilities : T he 
facilities of the VOLUME parameter 
allow the programmer to: 

• Bequest private volumes (PRIVATE) 

• Request that private volumes remain 
mounted until the end of the job 
(RETAIN) 

• Select volumes Mhen the data set 
resides on more than one volume 

( volu me-seq uence- nu mber) 

• Request more than one nonspecific 
volume (volume-count) 

• Identify specific volumes (SER and 
SEE) 

These facilities are all optional. 
The programmer can omit the VOLUME 
parameter when defining a new data 
set, in which case the system assigns 
a suitable public or scratch volume. 

VOLU ME sub pa ra me ters: 

PRIVATE 

indicates that the volume on which 
space is being allocated to the data 
set is to be made private. If the 
PRIVATE, SER, and 8EF subparameters 
are omitted for a new output data set, 
the system assigns the data set to any 
suitable public or scratch volume that 
is available. 

RETAIN 

indicates that this volume is to 
remain mounted after the job step is 
completed. Volumes are retained so 
that data may be transmitted to or 
from the data set, or so that other 
data sets may reside in the volume. 
If the data set requires more than one 
volume, only the last volume is 
retained; the other volumes are 
previously dismounted- Another job 
step indicates when to dismount the 
volume by omitting RETAIN. If each 
job step issues a RETAIN for the 
volume, the retained status lapses 
when execution of the job is 
completed. 

volume-sequence-number 

is a 1- to 4-digit number that 
specifies the sequence number of the 
first volume of the data set that is 



read or written. The volume sequence 

number is meaningful only if the data 

set is cataloged and earlier volumes 
are omitted. 

volume-count 

specifies the number of volumes 
required by the data set. Unless the 
SER or REF subparameter is used this 
subparameter is required for every 
raultivolume output data set. 



SER 



specifies one or more serial numbers 
for the volumes required by the data 
sets. A volume serial number consists 
of one to six alphanumeric characters. 
If it contains fewer than six 
characters, the serial number is left 
justified and padded with blanks. If 
SER is not specified and DISP is not 
specified as NEW, the data set is 
assumed to be cataloged, and serial 
numbers are retrieved from the 
catalog. A volume serial number is 
not required for new output data sets. 
Two volumes should not have the same 
serial number. When the SER parameter 
is included, the volume is treated as 
PRIVATE commencing with allocation for 
the current job step. If this 
subparameter is specified, the UNIT 
parameter must also be specified. 



REF 



indicates that the data set is to 
occupy the same volume <s) as the data 
set identified by dsname *.ddname, 
♦.stepname.ddname, or *.stepname. 
procstep. ddname. Figure 12 shows the 
data set references. 

If SER or REF is not specified, the 
control program will allocate any 
nonprivate volume that is available. 

MMli-gajgaigt er -l D es cr iking Data Set Label) 
specifies information about the label 
or labels associated with the data 
set. If a data set is passed from a 
previous job step, label information 
is retained from the DD statement that 
specified DISP=(,PASS) . A LABEL 
parameter, if specified in the DD 
statement receiving the passed data 
set, is ignored. If the LABEL 
parameter is omitted and the data set 
is not being passed, standard labeling 
is assumed. The operating system 
verifies mounting when the label 
parameter specifies standard labels 
(SL) or standard and user labels 
(SUL) . Nonstandard labels can be 
specified only when installation- 
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Option 



|REF=dsname 



| Refers to 

H 

J A data set named dsname 

+ 



I 
J 



|REF=*. ddname 



| A data set indicated by DD statement ddname in the 
j current job step 



H 

J A data set indicated by DD statement ddname in the job 
J step stepname 
H 



I BEF=*. stepname. ddname 
I 



, 

| REF=*. stepname. procstep. ddname} A data set indicated by DD statement ddname in the J 
| | cataloged procedure step procstep called in the job stepl 

| {stepname (see "Using the Cataloged Procedures") \ 

i i '. j 

Figure 12. Data Set References 



written routines to write and process 
nonstandard labels have been 
incorporated into the operating system 
(see "User Label Processing" and the 
publication OS/VS Tape Labe l s for 
information about writing these 
routines) . 

LABE L , S ubpart meters: 

data-set-sequence- number 

is a 4-digit number that identifies 
the relative location of the data set 
with respect to the first data set in 
a tape volume. (For example, if there 
are three data sets in a magnetic tape 
volume, the third data set is 
identified by data set sequence number 
0003.) If the data set sequence 
number is not specified, the operating 
system assumes that it is 0001. (This 
option should not be confused with the 
volume seguence number, which 
represents a particular volume for a 
data set. ) 

f AL ""N 

AUL 
BLP 
LT8 

NL 
£L 
NSL 

specifies the kind of label used for 
the data set. AL indicates American 
National Standard labels. AUL 
indicates American National Standard 
user labels. BLP indicates that the 
system is not to perform label 
processing for the tape data set. LTM 
indicates that the data set has a 
leading tapemark. A , indicates that 
the data set has standard labels and 
another subparameter follows. NL 
indicates no labels. S.L indicates IBH 
standard labels. NSL indicates 



nonstandard label. SUL indicates IBM 
standard and user labels. 

EXPDT=yyddd 

RETPD=xxxx 

specifies how long the data set shall 
exist. The expiration date, 
EXPDT=yyddd, indicates the year (yy) 
and the day (ddd) that the data set 
can be deleted. The period of 
retention, RETPD=xxxx, indicates the 
period of time, in days, that the data 
set is to be retained. If neither is 
specified, the retention period is 
assumed to be zero. 

PASSWORD 

indicates that the data set is to be 
made accessible only when the correct 
password is issued by the operator. 
The operating system assigns security 
protection to the data set. In order 
to retrieve the data set, the operator 
must issue the password on the 
console. 

NOPWREAD 

indicates that the data set can be 
read without the password, but the 
correct password must be issued by the 
operator before the data set can be 
changed, extended, or deleted. 



IN 



OUT 



indicates that the data set is to be 
processed for input only. 



indicates that the data set is to be 
processed for output only. 

DISP Parameter (Specifyin g Data Set Status 

and..pisposition) 

describes the status of a data set and 
indicates what is to be done with it 
after its last use, or at the end of 
the job. The job scheduler executes 



the requested disposition functions at 
the completion of the associated job 
step. If the step is not executed 
because of an error found by the 
system before trying to initiate the 
step (e.g., an error in a job control 
language statement) , the remaining 
statements are read and interpreted; 
however , none of the succeeding steps 
are executed, and the requested 
dispositions are not performed. This 
parameter can be omitted for data sets 
created and deleted during a single 
job step. Additional information 
about the relationship between the 
DISP parameter and the volume table of 
contents is contained in "Additional 
File Processing Information." 

2IS P_3Lub £a ra meters : 

NEs" 

indicates that the data set is being 
generated in this step. If the status 
is omitted, the NEW subparameter is 
assumed. 



OLD 



SHR 



MOD 



indicates that the data set specified 
in the DSNAME parameter already 
exists. 
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concurrently operat 
job will have to wa 
particular file is 
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Note: For VSAM data sets, this 
subparameter alone does not guarantee 
that sharing will take place. For 
more information see the chapter "Data 
Security and Integrity" in the 
publication OS/VS Virtual storage 
Jk££££S_ Method (VSAM) Progr ammer 's 
Guide. 



causes logical positioning after the 
last record in the data set. It 
indicates that the data set already 
exists and that it is to be added to, 
rather than read, When HOD is 
specified and neither the volume 
serial number is given nor the data 
set cataloged or passed from an 
earlier job step, MOD is ignored and 



NEW is assumed. If the volume serial 
number is given, it is assumed that 
the data set is on the specified 
volume. 



DELETE 

causes the space occupied by the data 
set to be released for other purposes 
at the end of the current step. If 
the data set is cataloged, and the 
catalog is used to locate it, 
reference to the data set is removed 
from the catalog. If it is on a mass 
storage device, all references are 
removed from the volume table of 
contents, and the device space is made 
available for use by other data sets. 
If the data set is on tape, the volume 
in which the data set resides is then 
available for use by other data sets. 



KEEP 



PASS 



ensures that the data set remains 
intact until a DELETE parameter is 
exercised in either the current job 
or some subsequent job. If the data 
set is on a mass storage device, it 
remains tabulated in the volume table 
of contents after completion of the 
job. When the volume containing the 
data set is to be dismounted, the 
operator is advised of the 
disposition. 



indicates that the data set is to be 
referred to in a later step of the 
current job, at which time its 
disposition may be determined. When a 
subsequent reference to this data set 
is encountered, its PASS status lapses 
unless another PASS is issued. The 
final disposition of the data set 
should be specified in the last DD 
statement referring to the data set 
within the current job. 
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CATLG 



causes the creation, at the end of the 
job step, of an index entry in the 
system catalog pointing to the data 
set. The data set can be referred to 
by name in subsequent jobs, without 
the need for volume serial number or 
device type information from the 
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prog Tanner, 

KEEP. 



Cataloging also implies 



ONCATLG 

causes the index entry that points to 
this data set to be removed from the 
index structure at the end of this 
step. The data set is not deleted. 
If it is on a mass storage volume, 
reference to it remains in the volume 
table of contents. 

Note; The absence of DELETE, KEEP, 
PASS, CATLG, and ONCATLG indicates 
that no special action is to be taken 
to alter the permanent or temporary 
status of this data set. If the data 
set was created in this job, it will 
be deleted at the end of the current 
step. If the data set existed before 
this job, it will be kept. 

The third subparameter indicates the 
disposition of the data set in the event 
the job step terminates abnormally. This 
is the conditional disposition 
subparameter. Explanations for DELETE, 
KEEP, CATLG, and UNCATLG are the same as 
those for normal termination. The 
following points should be noted when using 
the third subparameter. 

• If a conditional disposition is not 
specified and the job step abnormally 
terminates, the reguested disposition 
{the second subparameter) is performed. 

• Data sets that were passed but not 
received by subsequent steps because of 
abnormal termination will assume the 
conditional disposition specified the 
last time they were passed. If a 
conditional disposition was not 
specified at that time, all new data 
sets are deleted and all other data 
sets are kept. 

• A conditional disposition other than 
DELETE for a temporary data set is 
invalid and the system assumes that it 
is DELETE. 



SYSO UT Paramet er (Routing Da ta Set through 

the Out put Stream) 

schedules a printing or punching 
operation for the data set described 
by the DD statement. 



SYS OUT Subparameters : 

classname 

specifies the system output class on 
which the data set is to be written. 
A classname is an installation 
specified 1-character name designating 
the output class to which the data set 
is to be written. Each classname is 



related to a particular output unit. 
Valid values for the SYSOUT parameter 
are A through Z and through 9. A is 
the standard output class. 

M2te: Classes through 9 should not 
be used except in cases where the 
other classes are not sufficient. 
These classes are intended for future 
features of systems. 

(classnamef , program-name ][ , form-no }) 
classname specifies the class 
associated with the output device to 
which the output data se't is to be 
written. output writers route data 
from the output classes to system 
output devices. The DD statement for 
this data set can also include a unit 
specification describing the 
intermediate mass storage device and 
an estimate of the space required. If 
there is a special installation 
program to handle output operations, 
its program-name should be specified. 
Program-name is the member name of the 
program, which must reside in the 
system library. If the output data 
set is to be printed or punched on a 
specific type of output form, a 
4-digit form number should be 
specified. Form-no. is used to 
instruct the operator of the form to 
be used in a message issued at the 
time the data set is to be printed. 

Notes: 

* If both the program-name and form-no. 
are omitted, the delimiting parentheses 
can be omitted. 

• If the Direct SYSOUT Writer is used to 
write a data set, both the form-no. 
and program-name are ignored. All 
parameters on the DD statement, i.e., 
UNIT or SPACE, are also ignored. 



FCB, par amete r ^Specifying output for a 3211 

Printer or, a 3525 Card Punch) 

is used to select the forms control 
image to be used to print an output 
data set on a 3211 printer, or a 3525 
card punch with the read feature. The 
FCB parameter will be ignored if the 
data set is not written to either one 
of these devices. The FCB parameter, 
the DDNAHE parameter and the DCB 
subparameters RKP, CYLOFL, and INTVL, 
are mutually exclusive. 



FCB Subparameters : 

image- id 

identifies the image to be loaded into 
the forms control buffer. For further 
information on the forms control 
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buffer, see the publication OS/VS n Data 
BiM2g!§ n t £° r System Programme rs. 



ALIGN 

VERIFY 

requests the operator to check the 
alignment of the printer forms before 
the data set is printed or to verify 
that the image displayed on the 
printer is the desired one. 



AMP Parameter (S pecifying Information fo r 

VSAH Pr ocess in g ) 

specifies information to be used for 
processing by VSAM. The AMP parameter 
and its sub para meters are described 
under "VSAM-only JCL Parameter" in the 
chapter "VSAM File Processing". 
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JO BUB statement may be 
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or permanent members 
see "Checklist for 
and "Libraries" for 



The STEPLIB DD statement may appear in 
any position among the DD statements for 
the job step. The library should be 
defined as OLD. If the library is to be 
passed to other job steps, the second 
subparameter of the DISP parameter should 
be coded PASS. A later job step may then 
refer to the library by coding its STEPLIB 
DD statement as follows: 



ADDITIONAL , DP .„ STATEMENT FACILITIES 



//STEPLIB DD DSNAME=*.stepname. STEPLIB, X 
// DISP= (OLD, PASS) 



By specifying certain ddnames, the 
programmer can request the operating systei 
to perform additional functions. The 
operating system recognizes these 
special- purpose ddnames: 

• JOBLIB and STEPLIB to identify private 
user libraries 

• SYSABEND and SYSUDUMP to identify data 
sets on which a dump may be written 

» SYSCHK to identify the checkpoint data 
set written during the original 
execution of a processing program. 

• JOBCAT and STEPCAT to identify VSAH 
user catalogs. 



JOBLIB AND STEPLIB DD STATEMENTS 



The JOBLIB and STEPLIB DD statements are 
used to concatenate a user's private 
library with the system library 
(SYS1.LINKLIB) . Use of JOBLIB results in 
the system library being combined with the 
private library for the duration of a job; 
use of STEPLIB, for the duration of a job 
step. During execution, the library 
indicated in these statements is scanned 
for a module before the system library is 
searched. 

The JOBLIB DD statement must appear 
immediately after the JOB statement and its 
operand field must contain at least the 
DSNAME and DISP parameters. The DISP 
parameter must contain PASS as the second 
subparameter if the library is to be made 



The STEPLIB statement overrides the 
JOBLIB statement if both are present in a 
job step. 



SYSABEND AND SYSUDUMP DD STATEMENTS 



The ddnames SYSABEND or SYSUDUMP 
identify a data set on which an abnormal 
termination dump may be written. The dump 
is provided for job steps subject to 
abnormal termination. 

The SYSABEND DD statement is used when 
the programmer wishes to include in his 
dump the problem program storage area, the 
system nucleus, and the trace table if the 
trace table option had been requested at 
system generation time. 

The SYSUDUMP DD statement is used when 
the programmer wishes to include only the 
problem program storage area. 

The programmer may rout the dump 
directly to an output writer by specifying 
the SYSOUT parameter on the DD statement. 
In a multiprogramming environment, the 
programmer may also define the intermediate 
direct-access device by specifying the UNIT 
and SPACE parameters. 



SYSCHK DD STATEMENT 



The SYSCHK DD statement is required when 
a job is being submitted for deferred 
checkpoint/restart. It defines a 
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checkpoint data set written during the 
original execution of a processing program. 
For detailed information about the 
checkpoint/restart facilities, see the 
publication OS/VS Checkpoint/Restart. 

The SYSCHK DD statement must immediately 
precede the first EXEC statement of the 
resubmitted job when restart is to begin at 
a checkpoint. The RESTART parameter must 
be included on the JOB statement; otherwise 
the SYSCHK DD statement will be ignored. 

Different SYSCHK DD statement parameter 
specification rules apply depending on 
whether the checkpoint data set is 
cataloged or not. These rules are 
discussed in detail in the publication 
OS/VS JCL Reference . 



JOBCAT AND STEPCAT DD STATEMENTS 



The JOBCAT DD statement 
VSAM user catalog that is 
throughout a VSAM process! 
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term PEND in the operation field. The PEND 
statement is not used for cataloged 
procedures. For further information about 
in-stream procedures, see "Testing a 
Procedure as an In-Stream Procedure" in 
"Using the Cataloged Procedures." 



COMMAND STATEMENT 
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The command statement contains 
identifying characters (//) in columns 1 
and 2, a blank name field, a command, and, 
in most cases, an operand field. The 
operand field specifies the job name, unit 
name, or other information being 
considered. 



Sot®* A command statement cannot be 
continued, it must be coded on one card or 
card image. 



PROC STATEMENT 
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DELIMITER STATEMENT 



The delimiter statement marks the end of 
a data set in the input stream. The 
identifying characters /* must be coded 
into columns 1 and 2, the other fields are 
left blank. Comments are coded as 
necessary. 

Note: The end of a data set need not be 
marked in an input stream that is defined 
by a DD * statement. 



NULL,, STATEMENT 



PEND STATEMENT 



The PEND statement must appear as the 
last control statement in an in-stream 
procedure and marks the end of the 
in-stream procedure. It must contain the 



The null statement is used to mark the 
end of a job in an input stream. It causes 
the card reader file to be effectively 
closed. The identifying characters // are 
coded into columns 1 and 2, and all 
remaining columns are left blank. 
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COMMENT STATEMENT 
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When the comment statement is printed on 
an output listing, it is identified by the 
appearance of asterisks in columns 1 
through 3. 



BATCH COMPILATION 



The batch compile feature is used to 
compile multiple programs or subprograms 
with one invocation of the compiler. The 
object programs produced from the batch 
compilation may be link-edited into either 
one load module or separate load modules. 
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The CBL card must be the first card in 
each program within a batch mode. The CBL 
card, in addition to separating logical 
program units, may be used to change 
existing options (as they were specified 
or defaulted to on the EXEC card) for that 
individual program, and has the following 
format : 



! 



1 



fCBL [option 1 ][ , option 2 ].. .[ , option * n ] | 
I I 



The letters CBL may appear in any three 
consecutive columns 1 through 72, and the 
option (s) specified may be any PAHM 
compiler option (s) e xce pt SIZE, BUF, BATCH, 
L120, L132, SYMDMP, and WL, which are 
ignored if indicated. 



A sequence number may appear in columns 
1 through 6 of the CBL card. 



• In most cases, an option specified on 
the CBL card overrides the correspond- 
ing EXEC card option for compilation 
of that one program only. However, 
this is not true in the case of options 
that require use of a file that will 

be used in a subsequent compilation 
in the batch, or in a subsequent job 
step. Generally speaking, it is unwise 
to use the CBL card to specify any such 
option, because use of that file in 
compilation may cause an abend. Options 
in this category are LOAD, LIB, DECK, 
FDECK, and CDECK. 

If some programs in a batch compilation 
require the use of one of these options 
and the other programs do not, specify 
the option on the EXEC card, and then 
specify the NO... form of the option 
on those CBL cards where the option is 
not wanted. For example, if programs 
2, 3, and 5 in a batch compilation 
require FDECK and programs 1 and 4 
require NOFDECK, then FDECK should 
be specified (or defaulted to) on the 
EXEC card, and NOFDECK specified on 
the CBL cards for programs 1 and 4 . 
(It would not be possible to specify 
or default to NOFDECK on the EXEC 
card and then override it with FDECK 
on a CBL card.) 

* If a CBL card is present and BATCH is 
not specified on the EXEC card, the CBL 
card is regarded as an invalid 
statement. 



• If the compiler NAME option is 

specified on the CBL card, a linkage 
editor NAME control card is generated 
for this compilation, facilitating the 
link-editing of the program into a 
separate load module. 



* The output of a batch compilation may 
be executed only if the member name 
specified at compile time is the name 
specified at execution time. 

* The batch option may be used in 
conjunction with BASIS. This facility 
provides the COBOL programmer with the 
ability to combine a (multiple) BASIS 
library member {s) and/or a (multiple) 
COBOL source program <s) with one 
invocation of the compiler. 

* The BATCH option and the 'SYMDMP option 
are mutually exclusive. 
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When the batch option is used in 
combination with BASIS, the following rules 
apply: 

1. All the BASIS library ©embers to be 
compiled must be members of the 
partitioned data set (s) referred to by 
the SYSLIB DD data set name(s). 

2- Each BASIS library member must contain 
only one source program. 

Figure 13 shows that with one invocation 
of the COBUCL cataloged procedure (see the 
chapter "Using the Cataloged Procedures"), 
the programs C0MPILE1, CGMPILE2, and 
C0MPILE3 are compiled and tvo load modules 
created as follows: 



1. COMPILE 1 and C0MPILE2 are link-edited 
together to form one load module with 
the member name of CGMPILE2, a typical 
called/calling situation. (For 
further discussion of articulation 
between COBOL programs, see the 
chapter "Called and Calling 
Programs".) In this case, the entry 
point of the load module is still the 
first program, COMPILE"!. 

2. COMPILES is link-edited to create the 
load module with the member name of 
COMPILES. 

Figure 14 shows that with one invocation 
of the COBUCL procedure the programs PR0G1 
and PR0G2 and BASIS library members PAYROLL 
and PAYR0LL2 are compiled and four load 
modules are created. (An example of how to 
execute load modules created with the BATCH 
feature using the procedure COBUCL is given 
in Figure 13.) 



1, BATCH, MS GLEVEL=1 

COBUCL, P ARM. COB=« BATCH, NAME' 

* 



//jobname 


JOB 


//COMPILE 


EXEC! 


//COB.SYSIN 


DD 


CBL NONAME 




ID DIVISION. 




PROGRAM-ID. 


C0MPILE1. 


CBL NAME 




ID DIVISION- 




PROGRAM-ID. 


COMPILE 2. 



DSN=BATCHRUN,SPACE=(TRK, (10,5,2) ) , 



CBL NAME 

ID DIVISION. 
PROGRAM-ID. C0MPILE3, 



/* 

//LKED.SYSLHOD DD 

/* 

//COMPILE2 EXEC PGM=COMPILE2 

//STEPLIB2 DD DSN=BATCHRUN2,DISP=SHR,.... 

// (Cards needed to execute COMPILE1 and COMPILE2) 

/* 

//COMPILE3 EXEC PGM=COMPILE3 

//STEPLIB DD DSN=BATCHRUN,DISP=SHR,.... 

// (Cards needed to execute COMPILES) 

/* 



*In the compile step, no special JCL is needed for SYSLIN because the COBUCL cataloged 

procedure is used (see the chapter "Using The Cataloged Procedures"). 
*In the link-edit step, a partitioned data set is created with the DSN of BATCHRUN. 



Figure 13. Example of a Batch Compilation 
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//jobname 


JOB 


//COMP 


EXEC 


//COB.SYSLIB 


DD 


//COB.SYSIN 


DD 


CBL 


NAME, NOLI B 



CBL 
BASIS 

CBL 
BASIS 

CBL 



/* 



//LKED.SYSLMOD* 
/* 



1,BATBASIS,MSGLEVEL=1 

COBOCL , P AR H. COB=« BATCH, NAME, LIB' 

DSN=LIBPOS,... » 



IDENTIFICATION DIVISION. 
PROGRAM-ID. PR061. 



NAME 

PAYROLL 

NAME 

PAYBOLL2 

NAME, NOLIB 

IDENTIFICATION DIVISION 

PROGRAM-ID. PROG2. 



DD 



DSN=BATCHBAS,SPACE=(TRK, (10,5,2) ) , 



x This partitioned data set contains as separate members PAYROLL and PAYROLL2. 
2 The load modules of these four COBOL programs exist as separate members of a 

partitioned data set named BATCHBAS. 
i 

Figure 14. creation of Four Load Modules with Programs PROG1 and PROG2 and BASIS 
Library Members PAYROLL and PAYROLL2 



DATA SET REQUIREMENTS 



COMPILER 



A number of data sets may be defined for 
a compilation job step; six of these 
(SYSUT1, SYSUT2, SYSUT3, SYSUT4, SYSIN, and 
SYSPRINT) are always required. SYS0T5 is 
required if the SYMDMP or TEST option is 
invoked. SYSUT6 is required if FIPS 
flagging is requested. Additional data 
sets (SYSLIN, SYSPONCH, SYSTERM, and SYSLIB 
and/or other COPY libraries) are optional. 



For compiler data sets other than 
utility data sets, a logical record size 
can be specified by using the LRECL and 
BLKSIZE subparameters of the DCB parameter. 
The values specified must be permissible 
for the device on which the data set 
resides. LRECL equals the logical record 
size, and BLKSIZE equals LRECL multiplied 
by S.# where n is equal to the blocking 
factor. If this information is not 
specified in the DD statement, it is 
assumed that the logical record sizes for 
the unblocked data sets have the following 
default values: 



Unblocked 


Default 


Data Set 


Value ib}rtesj_ 


SYSIN 


80 


SYSLIN 


80 


SYSPUNCH 


80 


SYSLIB or other 




COPY libraries 


80 


SYSPRINT 


121 or 133 


SYSTERM 


121 



Note; The default for SYSPRINT has a value 
of 133 if 132 is selected with LSTCOMP or 
LSTONLY. 

The ddname that must be used in the DD 
statement describing the data set appears 
as the heading for each description that 
follows. Figure 15 lists the function, 
device requirements, and allowable device 
classes for each data set. (See "Appendix 
D: Compiler Optimization" for further 
information on blocked compiler data sets 
other than utility data sets.) 



SYSU?1, SJSUT2. SYSUT3, SYSUT4, SYSUT5, 
SYSUT6 



The DD statements using these ddnames 
define utility data sets that are used by 
the compiler when processing the source 
module. The data set defined by the SYSUT1 
DD statement must be on a mass storage 
device. Except for SYSUT5, which is needed 
at execution time, these data sets are 
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temporary and have no connection with any 
other job step. For example, the DD 
statement 

//SYSUT1 DD ONIT=SYSDA,SPACE=(TRK, (40,10)) 

specifies that the data set is to be 
written on any available mass storage 
device, with a primary allocation of U0 
tracks. Additional tracks, if required, 
are to be allocated in groups of 10. The 
data set is to be deleted at the end of the 
job step (by default). 

Note: The NULLFILE or DUMM? parameter or 
the RLSE subparaaeter of the SPACE 
parameter should never be specified for any 
of these data sets. In addition, the data 
sets must be single volume, since the 
compiler uses the TCLOSE facility 
extensively and TCLOSE will not reposition 
multivolume data sets. 



SYSIN 



The data set defined by the SYSIN DD 
statement contains the input for the 
compiler, i.e., the source module 
statements that are to be processed. The 
data set assigned to this DD statement is a 
sequential data set, or a member of a 
partitioned data set. It may be part of 
the input stream. If so, it is commonly 
referred to as a SYSIN data set. For 
example, 

//SYSIN DD * 

specifies that the input data set follows 
in the input stream. 



SYSPRINT 



This data set is used by the compiler to 
produce a listing. Output may be directed 
to a printer, a mass storage device, or a 
magnetic-tape device. The listing will 



include the results of the default or 
specified options of the PARS parameter 
(i.e., diagnostic messages, the object code 
listing) . For example, in the DD statement 

//SYSPHINT DD SYSO0T=A 

SYSOOT is the disposition for printer data 
sets, and A is the standard output class 
for printer data sets. 



s_XST£IU 



The data set defined by the SYSTESM DD 
statement is used for certain compiler 
output for a TSO terminal user when the 
TERM option is specified. The compiler 
output consists of diagnostic and progress 
messages and compiler statistics. For 
example; 

//SYSTESH DD TERH=TS 

TERK=TS indicates that the SYSTERH data 
set is to be directed to the TSO terminal. 



SYSPUNCH 



The data set defined by the SYSPUNCH DD 
statement is used to punch an object module 
deck or, if FDECK or CDECK is specified, to 
punch a source deck. This data set can be 
directed to a card punch, mass storage 
device, or magnetic tape. For example, in 
the DD statement 

//SYSPONCH DD SYSOUT=B 

SYSOOT is the disposition for punch data 
sets, and B is the standard output class 
for punch data sets. 

Note: The SYSPUNCH DD statement is not 
required if NODECK is in effect. SYSPUNCH 
may be either a sequential data set or a 
member of a PDS. 
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ddnane 



Type 



Function 



Device 
Requirements 



Allowable 
Device Classes 



SYSIN 
(required) 



SYSPRINT 
(required) 



Input/output 



SYSTERM 
(optional) 



SYSPUNCH 
(optional) 



SYSLIN 
(optional) 



Reading the source 
program 



Card reader 
Intermediate storage 



SYSSQ, SYSDA, or the 
input stream device 
{specified by DD * 
or DD DATA) 



Writing the storage 
map, listings, and 
and messages 



Printer 
Intermediate storage 



SYSSQ, SYSDA, stand- 
ard output class A 



Writing diagnostic 
and progress messages 



Output device 
TSO terminal 



Punching the object 
module deck 



Card punch 
Hass storage 
Magnetic tape 



Creating an object 
module data set as 
output from the com- 
piler and input to 
the linkage editor 



Mass storage 
Magnetic tape 



SYSCP, SYSSQ, SYSDA, 
standard output 
class B 



SYSSQ, SYSDA 



-H 



SYSUT1 
(required) 



Utility 



SYSUT2 
(required) 



SYSDT3 
(required) 



SYSUT4 
(required) 



SYSUT5 



Work data set needed 
by the compiler 
during compilation 



Mass storage 



Work data set needed 
by the compiler 
during compilation 



Mass storage 
Magnetic tape 



Work da 
by the 
during 



ta set needed 

compiler 

compilation 



Mass storage 
Magnetic tape 



Work da 
by the 
during 



ta set needed 

compiler 

compilation 



Hass storage 
Magnetic tape 



Work da 
when SY 
option 



ta set needed 
MDMP or TEST 
is in effect 



Mass storage 
Magnetic tape 



SYSDA 



SYSSQ, SYSDA 



SYSSQ, SYSDA 



SYSSQ, SYSDA 



SYSSQ, SYSDA 



SYS0T6 



Utility 



Work data set needed 
when LVL option is in 
effect 



Mass storage 
Magnetic tape 



SYSSQ, SYSDA 



SYSLIB 
and/or 
other COPY 
libraries 
(optional) 



Library 



Optional user source 
program libraries 



Mass storage 



SYSDA 



gote; Once created, a SYSUT5 data set can be moved only to a device of the same type. 
That is, if the SYSUT5 data set is put on tape at compile time, that data set cannot be 
moved to a disk at execution time. The SYSUT5 data set must be unblocked. 

Figure 15. Data Sets Used for Compilation 



SYSLIN 



The device defined by the SYSLIN DD 
statement is used by the compiler to store 



an object module. It may be on a mass 
storage or magnetic tape device. For 
example: 
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//SYSLIN DD 

// 

// 

// 

The tempo rar 
GGFILE, the 
indicates th 
added to in 
passed to an 
the linkage 
assigned for 
device on wh 
allocated to 
needed, trac 



DSNAME=&&GOFIL£, 
DISP= (MOD, PASS) , 
UNIT=SYSDA, 
SPACE=(TfiK, (30,10)) 



y name o 
paramete 
at the d 
this job 
other jo 
editor s 

storage 
ich 30 t 

the dat 
ks are a 



f the data 
r DISP=(M0 
ata is to 

step and 
b step, wh 
tep. The 

is a lass 
racks are 
a set. If 
llocated 1 



set is 
D,PASS) 
be created or 
is to be 
ich may be 
device to be 

storage 
initially 
sore space is 
at a time. 



Note: The SYSLIN DD statement is not 
required if NOLQAD is in effect- SYSLIN 
may be either a data set or a member of a 
PDS. 



The SYSLIB and other COPY library DD 
statements are not reguired if NOLIB is in 
effect. 



LINKAGE EDITOR 



Five data sets are reguired for linkage 
editor processing. Others may be necessary 
if secondary input is specified. In the 
following discussions, the ddname that must 
be used in the DD statement describing the 
data set appears as the heading for each 
description of the particular data set. 
For any user-defined data set, the ddname 
is defined by the programmer. Figure 16 
lists the function, device reguirements, 
and allowable device classes for each data 
set. 



3X2MN 



SYSLIB and/or Other COPy libraries 



These DD statements define the libraries 
(PDS's) that contain the data requested by 
COPY statements (in the source module) or 
by a BASIS card in the input stream. The 
DD statement must be SYSLIB if a BASIS 
library is to be included, or if the COPY 
statement does not specify a library name 
(by qualifying the text name). Libraries 
must always be on mass storage devices. 
Note that more than one partitioned data 
set may be used for the library function by 
concatenating them with SYSLIB (see 
"Libraries" for an example). Although only 
one SYSLIB statement may be used in a 
compilation job step, multiple user-defined 
COPY libraries may be used. For example, 
in the DD statements 

//SYSLIB DD DSNAME=OSERLIB,DISP=OLD 

//HOUSELIB DD DSNAME=COPYX,DISP=OLD 
//PRIVLIB DD DSNAME=COPYZ,DISP=OLD 



the names of the source libraries are 
OSERLIB, COPYX, and COPY2. DISP=OLD 
indicates that the libraries have been 
created in a previous job and are 
cataloged, or have been created in a 
previous step in this job. No other 
information need be given if the specified 
libraries have been cataloged. 

Notes: Maximum blocksize for any COPY 
library is 16K (there is no such 
restriction for BASIS). 

When concatenating SYSLIB, the library 
with the largest blocksize must be 
specified in the first DD statement. 



The SYSLIN DD statement defines the data 
set that is primary input to linkage editor 
processing. Normally this data set 
consists of the output from a previous 
compilation job step. The primary input 
may also be linkage editor control 
statements, such as the INCLUDE, LIBRARY, 
or OVERLAY statements (see "Calling and 
Called Programs") . The input device 
assigned to this data set is either the 
device transmitting the input stream, if 
the input is an object module deck, or a 
device designated by the programmer. 
However, the data set may simply be passed 
from the previous compilation job step. 
For example, in the DD statement 

//SYSLIN DD DSNAME=*.STEPNAME.SYSLIN, X 
// DISP= (OLD, DELETE) 

the data set is defined in the SYSLIN DD 
statement contained in the compiler job 
step, STEPNAME. DISP= (OLD, DELETE) 
indicates that the data set was created in 
a previous job step and is to be deleted at 
the end of this job step. 

SYSPRINT 



The data set defined by the SYSPRINT DD 
statement is used by the linkage editor to 
produce a listing. For example: 

//SYSPRINT DD SYSOOT=A 

Output may be directed to a printer or to 
an intermediate data set. The listing may 
include any options specified by the PAfiM 
parameter of the EXEC statement (a module 
map or cross reference list, diagnostic or 
informative messages, etc.). 
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ddname 



Type 



Function 



Device 
Requirements 



Allowable 
Device Classes 



j 

input | 

i f i ed J 

I 

■» 

t I 
I 
i 



SYSLIN 

(required) 



Input/ 
output 



Primary input data, 
normally the output 
of the compiler 



Mass storage 
Magnetic tape 
Card reader 



SYSSQ, SYSDA, or the 
stream device (spec 
by DD * or DD DATA) 



SYSPSINT 
(required) 



Diagnostic messages 
Informative messages 
Module map 
Cross-reference list 



Printer 
Intermediate 
storage 



SYSSQ, standard outpu 
class A 



SYSLMOD 

(required) 



Output data set for 
the load module 



Mass storage 



SYSDA 



SYS0T1 

(required) 



Utility 



Work data set 



Mass storage 



SYSDA 



SYSLIB 

(required) 
for COBOL 
Library 
subroutines 



Library 



Automatic call library 
(SYS1.C0BLIB is the 
name of the COBOL 
subroutine library) 



Mass storage 



SYSDA 



SYSTBRM 
(required 
if TERM op- 
tion is 
specified) 



Numbered error/warning 
messages 



Printer 

TSO terminal 



Oser-specified 
(optional) 



Additional object 
modules and load 
modules 



Mass storage 
Magnetic tape 



SYSDA, SYSSQ 



Pigure 16, Data Sets Osed for Linkage Editing 



SYSTEEM 



SYSLMOD 



The SYSTERM DD statement is optional; it 
describes a data set that is used only for 
numbered error/warning messages. Although 
intended to define the terminal data set 
when the linkage editor is being used under 
TSO, the SYSTERM DD statement can be used 
in any environment to define a data set 
consisting of numbered error/warning 
messages that supplements the SYSPRINT data 
set. 



The SYSLMOD DD statement defines the 
output data set, in this case the load 
module. The load module must be placed in 
a library as a named member. The library 
can be the Link Library (SYS1.LINKLIB) or < 
private user-defined library. Such 
libraries must always reside on a mass 
storage device, and space for the library 
is allocated when the library is created. 
For example, in the DD statement 



SYSTERM output is defined by including a 
SYSTERM DD statement and specifying TERM in 
the PARM field of the EXEC statement. When 
SYSTERM output is defined, numbered 
messages are then written to both the 
SYSTERM and SYSPRINT data sets. 



The SYSTERM DD statement is specified as 
follows: 



//SYSTERM DD SYSO0T=A 



//SYSLMOD DD DSNAME=SYS 1. LINKLIB(MEMBER) , X 
// DISP=OLD 



the load module, MEMBER, is stored as a 
member of the link library. DISP=OLD 
indicates that the library is already 
created and additions are to be made to it. 



//SYSLMOD DD DSNAME=LIB1 (BALANCE) , 
// DISP=(NEW,CATLG) , 

// VQLUME=SER=111111, 

// SPACE=(TRK, (40,10,1)) , 

// UNIT=SYSDA 
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The load module, BALANCE, is to be a member 
of a library, LIB1, which is to be created 
in this job step, with BALANCE as its 
firstmember. The mass storage volume to 
which it is directed is identified by the 
serial number, 111111. A primary quantity 
of 40 tracks is allocated to the library 
with an additional allocation for one 
256-byte record to be used for the 
directory. If more space is needed for the 
library, tracks are added, 10 at a time. 
(However, no additional space can be 
allocated for the directory.) 

H2te: If the load module is placed in a 
private library, the JOBLIB or STEPLID DD 
statements must be specified in subsequent 
jobs that execute load modules from the 
iibrary. 



SYSUT1 



The SYS0T1 DD statement defines a 
utility data set used by the linkage editor 
when processing object modules and load 
modules. The data set must be on a mass 
storage device. It is a temporary data set 
and has no connection with any other job 
step. For example: 



Oser-S pecj.f led Data gets 



Additional data sets may be defined for 
linkage editor processing. These data sets 
may be used as additional input sources of 
object modules or load modules. They may 
also be concatenated with the primary input 
data set or the automatic call library (see 
"Libraries") . 



LOADER 



One data set (SYSLIH) is required for 
loader processing. Three are optional 
(SYSLIB, SYSLQUT and SYSTEBH) . (These 
ddnames can be changed during system 
generation with the LOADER macro 
instruction.) In addition, any DD 
statements and data required by the loaded 
program must be included in the input deck. 

In the following discussions, the 
default ddname for the DD statement 
describing the data set appears as the 
heading for each description of the 
particular data set. 



//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK, (40,10)) 



The data set is initially allocated 40 
tracks on any available mass storage 
device. If more space is needed, tracks 
are added, 10 at a time. A temporary name 
is assigned to the data set for the job 
step. 



SYSLIB 



SYSL.IN 



The SYSLIN DD S 

set that is primar 
This input can be 
produced by the CO 
modules produced b 
both. The loader 
and load module co 
The data sets defi 
statements can be 
sets or members of 
or both. 



tatement defines the data 
y input to the loader, 
either object modules 
BOL compiler or load 
y the linkage editor, or 
allows both object module 
ncatenation on SYSLIH. 
ned by the SYSLIN DD 
either sequential data 
a partitioned data set. 



The SYSLIB DD statement assigns the 
named partitioned data set to the automatic 
call library from which modules may be 
automatically obtained by the linkage 
editor to resolve external references. 

//SYSLIB DD DSNAME=SYS1.C0BLIB,DISP=SHR 



This statement assigns the COBOL subroutine 
library to the automatic call library. 
When there is a possibility that the 
compiler may have generated calls to any 
COBOL library subroutines, the SYSLIB 
statement must be specified (see "Appendix 
B: COBOL Library Subroutines" for a list 
of library subroutines, their functions, 
and entry points). 



SYSJ.I§ 



The SYSLIB DD statement defines the data 
set containing IBM or user-written library 
routines to be included in the loaded 
program. The SYSLIB data set is searched 
when unresolved references remain after 
processing SYSLIH and, optionally, 
searching the link pack area of 0S/VS2 or 
the resident reenterable modules feature of 
OS/VS1 . The library may contain either 
object modules or load modules but not 
both. The data set defined by the SYSLIB 
DD statement must be a partitioned data 
set. 
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SYSLOOT 



The SYSLOOT DD statement defines the 
data set used for error and warning 
messages and for an optional map of 
external references. The data set must be 
a sequential data set. The record format 
of SYSLOOT is always assumed to be FBSA. 



EXECUTION TIME DATA SETS 



where: 

n is the blocking factor 



SYSPUNCH must be on a device where blocking 
is permitted. For example: 



//SYSPUNCH 

// 

// 

// 



DD UNIT=SYSSQ, 

DCB= (RECFM=FB, 
BLKSIZE=160) , 
LABEL= (,NL) 



Any number of data sets may be used for 
execution time processing. These data 
sets, or files, are identified in the 
source program, and each must be described 
by a DD statement. The ddname is used to 
link the DD statement to the COBOL ASSIGN 
clause in the source program that specifies 
the ddname. DD statement requirements for 
the DISPLAY, ACCEPT, EXHIBIT, and TRACE 
statements are discussed in the following 
text. DD statements that specify COBOL 
debugging aids and an abnormal termination 
dump are also discussed. Use of either the 
Sort or the RERUN feature requires 
additional DD statements. For information 
about these statements, see "Using the Sort 
Feature" and "Using the Checkpoint/Restart 
Feature." 



D ISPLAY Statemen t 



The DISPLAY statement reguires an 
associated DD statement unless the data is 
to be displayed on the console. The DD 
statements needed for each form of the 
DISPLAY statement are as follows: 



Example 1 



! identifier! 
} ...UPON SYSPUNCH 
literal 



//SYSPUNCH DD applicable parameters 



It is assumed that SYS PU NCH is an 
unblocked data set that has a logical 
record length of 80 characters. For 
example: 

//SYSPUNCH DD SYS0UT=B 



However, the programmer can specify a 
blocked data set by using the subparameters 
of the DCB parameter as follows: 

RECFM=FB, BLKSIZE=n*80 



Example 2 : 



When the UPON option is omitted, SYSOUT is 
the default option. 



DISPLAY 



[identifier 



'literal 



//SYSOUT DD applicable parameters 



It is assumed that SYSOUT is an 
unblocked data set that has a line width of 
121 characters (1-byte for the control 
character) . 

For example: 

//SYSOUT DD SYSOUT=A 

However, the programmer can specify an 
alternate line width, recording mode, 
and/or a blocked data set by using the DCB 
parameter. To specify an alternate line 
width, the subparameters of the DCB 
parameter are used as follows: 

LRECL=line width* 1 ,BLKSIZE=LRECL value 

To specify a blocked data set, the 
subparameters are used as follows: 

RECFH=FBA,LRECL=line width+1, 
BLKSIZE=n* (LRECL value), 

where: 

n is a blocking factor 

SYSOUT must be on a device where blocking 
is permitted. The extra character in LRECL 
allows for the carriage control character. 
For example, to specify an alternate line 
width, the following SYSOUT statement can 
be used. 

//SYSOUT DD SYSOUT=A,DCB=(LRECL=133, X 
// BLKSIZE=133) 
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To specify a blocked data set, the 
following SYSOUT statement can be used. 

//SYSOUT DD DSNAME=PRINTOUT, 
// UNIT=SYSDA,..., 

// DCB=(RECFM=FBA, 

// LRECL=121, 

// BLKSIZE=605) , 

// V0LUME=SER=111111 

Note ; If the problem uses the Sort/Merge 
feature, remember that SYSOUT is the 
default error message data set, and a 
conflict can arise. See "Additional DD 
Statements" in the chapter "Using the 
Sort/Merge Feature" for suggested 
solutions . 

Example 3: 

The DISPLAY statement can use a 
mnemonic-name rather than a system-name. 



DISPLAY 



identifier 



literal 



,UP3N mnemonic-name 



where mnemonic-name is associated with the 
word SYSPDNCH or SYSOUT in the Environment 
Division. 



// 



SYSPUNCH 



DD applicable parameters 



SYSOUT 
ACCEPT Statement 



The ACCEPT statement requires an 
associated DD statement unless the data is 
being accepted from the console, format 2 
of the ACCEPT statement is used, or ACCEPT 
MESSAGE is used (making possible use of the 
options DATE, DAY, and TIME). The DD 
statements for each form of the ACCEPT 
statement are as follows: 



Example 1; 

ACCEPT identifier 

Hhen the FROM option is omitted, SYSIN is 
the default option. 

//SYSIN DD applicable parameters 

E xample 2: 

ACCEPT identifier FROM mnemonic-name 

where mnemonic-name is associated with the 
word SYSIN in the Environment Division. 

//SYSIN DD applicable parameters 

It is assumed that SYSIN is an unblocked 
data set that has a logical record length 
of 80 characters. 



For example: 

//SYSIN DD * 

(data) 
/* 

However, the programmer can specify a 
blocked data set by using the subparameters 
of the DCB parameter as follows: 

RECFM=FB,BLKSIZE=n*80 

where: 

n is the blocking factor 

SYSIN must be on a device where blocking is 
permitted. For example: 



//SYSIN DD UNIT=2400,..., 
// DCB= <RECFM=FB, 

// BLKSIZE=160) , 

// LABEL=(,NL) 



If a logical record length of other than 80 
characters is desired, it must be specified 
in the LRECL field of the DCB parameter. 



EXHIBIT or TRACE Statement 



The EXHIBIT or TRACE statement requires 
a SYSOUT DD statement as discussed for 
DISPLAY. 

Note: If the job step already includes a 
SYSOUT DD statement for some other use, 
another may not be inserted since all 
SYSOUT output from any source in the job 
step will be merged onto the one SYSOUT 
data set defined for that job step. 



CQBOL D ebu gging, Aids 



If one or more of the options FLOW, 
STATE, and SYMDMP is in effect, the 
following DD statement must be used: 

//SYSDBOUT DD applicable parameters 

If the output is routed through the output 
stream and written on a system output 
device, the following may be used: 



DD 



SYS0UT=A 



//SYSDBOUT 

The recording mode is FBA. The user 
can, however, specify a blocked data set 
and alternate recording mode by using the 
DCB subparameters. 

Note: It is assumed that SYSDBOUT is an 
unblocked data set that has a line width of 
121 bytes (one byte for a control 
character) . 
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See the chapter "Symbolic Debugging 
Features" in this manual. 

The following DD statement must be used 
to make the COBOL library module ILBODBEO 
available at execution time: 

//STEPLIB DD DSN=SYS1.C0BLIB,DISP=SHR 

If an error message is printed by the 
debugging modules, the COBOL library module 
ILBODBEO is loaded dynamically from 
SYS1.C0BLIB. This module is not link 
edited into the COBOL object program. 



with the SYMDBP option which could include 
the aanormally terminating program and its 
callers, up to and including the main 
program. The //SYSABEND or //SYSUDUHP DD 
card need not be included. For a 
discussion of the symbolic dumping option, 
as well as of other COBOL symbolic 
debugging options, see the chapter entitled 
"Symbolic Debugging Features." 



COUNT Option 



Abno rma l T er a i- n a*,ion Dum p 

To obtain an operating system 
hexadecimal dump in case the job is 
abnormally terminated by the system, or by 
executing the COBOL statement CALL 
♦ILBOABNO 1 USING identifier, one of the 
following DD statements must be used: 

//SYSABEND DD applicable parameters. 

//SYSUDUHP DD applicable parameters. 

The dump provided when the SYSABEND DD 
statement is used includes the system 
nucleus, the program storage area, and a 
trace table, if the trace table option was 
reguested at system generation. The 
SYSUDUMP DD statement provides a dump of 
the program storage area. The applicable 
parameters are those for a physical 
sequential data set. If the dump is routed 
through the output stream and written on a 
system output device, the following DD 
statement may be used: 

//SYSUDUMP DD SYSOUT=A 

Ngj.e: If a COBOL program abnormally 
terminates, then a formatted dump is 
provided for all COBOL programs compiled 



If the COUNT option is in effect, the 
following DD statement must be used: 



//SYSDBOUT DD applicable parameters 



For example, if the output is routed 
through the output stream and written on a 
system output device, the following may be 
used: 

//SYSDBOUT DD SYSOUT=A 

In addition to the SYSDBOUT DD 
statement, the SYSCOUNT DD statement must 
also be used: 

//SYSCOUNT DD SYSOUT=A 



COBOL Subroutine Libr ary 



The user may concatenate a library of 
selected COBOL object-time subroutines with 
the link library. (For information on how 
this can be accomplished, see the section 
"Sharing COBOL Library Subroutines" in the 
chapter entitled "Libraries") . 
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USER NON-VSAM PILE PROCESSING 



This section describes the processing of 
non-VSAM files. A description of VSAM file 
processing is in the section "VSAM File 
Processing." 



requires changing input/output statements 
and recompiling the program. Changing a DD 
statement when a program is executed is a 
simple procedure. 



USER-DEFINED FILES 



Files that are processed in a COBOL 
program must be described as data sets to 
the operating system. Whenever a file is 
specified in a program by the following 
statement: 



SELECT [OPTIONAL] file- name 
ASSIGN TO assignment-name 



this file must be described in an FD 
file-name entry and in a DD statement in 
the execution- time job step. The ddname in 
the DD statement is a portion of the 
assignment-name {sometimes also known as 
"system-name") specified in the ASSIGN TO 
clause. In the assignment-name 

UT-2400-S-TAXRATE 



TAXRATE is the ddname portion of the 
assignment -name. 

No£e: The device-number specified in the 
assignment-name is ignored by the compiler. 
Actual device allocation is a function of 
the DD statement. 



As an example, consider a COBOL program 
that might be used in exactly the same way 
for several different master files. It 
might contain the clause 



SELECT MASTER ASSIGN TO 

DA-3330-D-MASTERA. .. . 

In that case, the following DD statements, 
used at different . tim e s f would assign the 
different named data sets to the program: 

//MASTER A DD DSNAME=MASTEB 1 ,. . . 
//MASTER A DD DSNAME=MASTER2 , . . . 
//MASTERA DD DSNAME=MASTER3, . . . 



If the first DD statement appears in the 
job step that calls for execution of the 
program, any reference within the program 
to MASTER is a reference to the data set 
named MASTER1; if the second DD statement 
appears, the reference is to MASTER2; if 
the third, the reference is to MASTER3. 

However, if a file-name within a program 
is always to be applicable to only a single 
data set, the names might be written as 
follows: 

SELECT TAXRATE ASSIGN TO 
UT-2400-S-TAXRATE. .. 



FILE NAMES AND DATA SET NAMES 



The terms "file" (COBOL usage 
set" (operating system usage) ha 
essentially the same meaning. T 
however, be a difference between 
file-name and the data set name, 
set name always represents a spe 
set. The file-name can, at diff 
times, represent different data 
DD statement allows a programmer 
at the time his program is execu 
specific data set that is to be 
with a particular file-name. Th 
can be especially powerful when 
input data sets. 
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The file-name is a name known within the 
COBOL program. Changing a file- name 



The applicable DD statement might be: 

//TAXRATE DD DSNAME=TAXRATE, . . . 

Of the names, the ddname portion of the 
assignment-name that appears in the ASSIGN 
clause and the ddname of the DD statement 
must always be the same. The file-name and 
the data set name may be the same, or they 
may be different. (Of course, the 
file-name in the SELECT sentence must be 
the same as the FD name.) 

If two or more files on direct- access 
devices have the same ddname and are open 
at the same time (i.e., the output from the 
files is being merged into one data set) , 
the files must have no conflicting 
attributes. The foregoing also applies to 
SYSOUT data sets if they are written on an 
intermediate direct-access device. 
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The use of the DISPLAY, EXHIBIT, or 
READY TRACE verbs causes the library to 
open the target ddname (SYSOUT, SYSPUNCH, 
etc.) If the programmer has also assigned 
one of his output files to the same ddname, 
he must ensure that he has opened, written, 
and closed his file before the first 
execution of any of the previously 
mentioned verbs. 



The full range of facilities available 
in BPAM are not available to the COBOL 
programmer. A partitioned data set may be 
referred to in COBOL only by treating its 
members as physical seguential data sets. 



Additional considerations when using the 
Sort feature are described under 
"Additional DD statements" in the chapter 
"Using the Sort Feature." 



FILE PROCESSING TECHNIQUES 



DATA SET ORGANIZATION 



SPECIFYING INFORMATION ABOUT A FILE 



Some of the information about the file 
must always be specified in the FD entry, 
SELECT sentence, APPLY, and other COBOL 
clauses. Other information must be 
specified in the DD statement. For 
example, the amount of space allocated for 
a mass storage output file must be 
specified in the DD statement by the SPACE, 
SPLIT, or SUBALLOC parameters. Certain 
characteristics of files cannot be 
expressed in the COBOL language, and may be 
specified on the DD statement for the file 
by the DCB parameter. This parameter 
allows the programmer to specify 
information for completing the data control 
block associated with the file (see 
"Additional File Processing Information" 
for a discussion of the data control block, 
and "Appendix C: Fields of the Data 
Control Block") . 

Each file used in the program must be 
referred to by a particular file processing 
technique. Four processing techniques are 
discussed in this publication. They are 
physical sequential (QSAM) f direct (BSAH, 
BDAM), relative {BSAM, BDAM) , and indexed 
(OISAM, BISAM). 

A fifth processing technique, called 
partitioned data organization (BPAM) , is 
discussed throughout the publication, when 
it is used for program storage. 
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A non-VSAM data set used by a COBOL 
program can have one of four types of 
organization: physical sequential, direct, 
relative, and indexed. The first type 
(sequential) may be on any input/output 
device that is supported. All other types 
must be on mass storage devices (see Figure 
17 for information in determining the file 
processing technique to be used, according 
to data set organization) - 



1. A physical sequential data set is one 
in which records are organized solely 
on the basis of their successive 
physical positions. 



2. A direct data set is one in which 
records are referred to by use of 
relative track addressing. An ACTUAL 
KEY specifies the track relative to 
the first track allocated to the data 
set and identifies the record on the 
track. 



3. A relative data set is one in which 
records are referred to by use of 
relative reco rd addressing. A NOMINAL 
KEY identifies the record location 
relative to the first record in the 
data set. 



k. An indexed data set is one in which 
records are arranged on the tracks of 
a mass storage device so as to permit 
access in logical sequence (according 
to a key that is part of every 
record) . A separate index or set of 
indexes maintained by the system 
indicates the location of each record. 
This permits random, as well as 
sequential, access to any record. 
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or omitted 
N=R 



Mass Storage 



BSAM 
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a mass storage 
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ACCESS RANDOM 
N=R 



Mass Storage 



BDAM 



Create and read a 
mass storage file 
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ACCESS SEQUENTIAL 
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N=D 



F,V,U,S 



Mass Storage 



BSAM 
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mass storage file 
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ACCESS RANDOM 
N=D or W (REWRITE) 



F,V,U,S 



Mass Storage 



BDAM 
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storage file sith 
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ACCESS SEQUENTIAL 
or omitted 
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Mass Storage 
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a mass storage 
file with indexed 
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ACCESS SEQUENTIAL 
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Mass Storage 
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Figure 17. Determining the File Processing Technique 
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ACCESSING A PHYSICAL SEQUENTIAL FILE 



A physical sequential file may only be 
accessed sequentially, i.e., records are 
read or written in the order in which they 
appear on the file. The file processing 
technique used to create and retrieve a 
physical sequential file is QSAM (Queued 
Sequential Access Method). Figure 18 shows 
the COBOL clauses that may be used with 
these files. Special considerations for 
these clauses are as follows: 

1. The RESERVE clause can be used to 
specify more buffer areas, allowing 
overlap of input/output operations 
with the processing of data. If this 
clause is not used, additional buffers 
may be specified by using the BOFNO 
option in the DD statement. If no 
additional buffer areas are specified, 
two buffers are reserved by the 
system. when the SAME AREA clause is 
specified for the file, the number of 
buffers used is determined from the 
RESERVE clause or if the RESERVE 
clause is not present, it is given a 
default of two. The BOFNO option in 
the DD statement is ignored if the 
SAME AREA clause is specified. 

2. If a WRITE AFTER POSITIONING statement 
is used, the record size specified 

in the FD entry must allow for the 
carriage control or stacker select 
character, even though the character 
is not to be printed or punched. 
For example, if the record size 
specified in the FD entry is 121, 
the actual record is 121 characters; 
however, only 120 characters are 
printed or punched. 

If the NOADV compiler is specified 
and a WRITE BEFORE/AFTER ADVANCING 
statement is used, the situation is 
the same as above; the record size 
specified in the FD entry must allow 
for the control character, even though 
the character is not to be printed. 

When the ADV compiler option is 
specified and a WRITE BEFORE/AFTER 
ADVANCING statement is used, the 
record size specified in the FD 
entry should be the same as the 
record to be printed. (The compiler 
adds one to the length specified in 
the FD when it sets the logical 
record length in the DCB.) 

Notes: 

• If the immediate destination of the 
record is a device that does not 
recognize a carriage control or 
stacker select character, the system 
assumes that the control character 



is the first character of the data. 
If the HRITE BEFORE/AFTER ADVANCING 
statement or the WRITE AFTER 
POSITIONING statement is not used, 
the first byte of the record is 
treated as data by the punch or 
printer. 

The compiler may direct extra 
records, containing the appropriate 
control characters, to the file to 
effect printer spacing as specified 
in the WRITE BEFORE/AFTER ADVANCING 
statement. These extra records are 
for spacing purposes only and will 
not appear externally if the file is 
assigned to an online printer. 
However, if the file is assigned to 
a device that does not recognize the 
control characters (for example, a 
tape or a direct-access device) , the 
extra records are written onto the 
file. These extra records are 
produced only if ADVANCING more than 
three lines is specified or if both 
the BEFORE and AFTER options are 
specified for a file. 

3. If the input device is the card 

reader, RECOBDING MODE IS F should be 
specified. If RECORDING MODE IS V or 
S is specified, the first 8 bytes of 
the record will be interpreted as the 
control bytes required for files with 
format V or S records. 

i*. If physical sequential files are on 
magnetic tape, the record block size 
should be at least 18 bytes. Records 
less than 18 bytes in length will be 
read with no problems, unless a parity 
check occurs. If a parity check 
occurs while reading a record less 
than 18 bytes, it will be treated as a 
noise record and skipped over. 

5. The S {standard) option can be 
specified in the DCB RECFM 
subparameter for a fixed/blocked 
record data set with only standard 
blocks (i.e., having no truncated 
blocks or unfilled tracks within the 
data set, except for the last block of 
the last track). If a fixed/blocked 
data set is created through the use of 
an American National Standard COBOL 
program, a truncated physical block 
may be written only by the executions 
of the CLOSE or CLOSE UNIT (or REEL) 
statement. Use of the standard block 
option (particularly for direct-access 
devices having the Rotational 
Positional Sensing feature) results in 
significant I/O performance 
improvements. 

6. The T {TRACK OVERFLOW) option can be 
specified for the DCB RECFM 
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Figure 18- COBOL Clause for Physical sequential File Processing 



subparameter of the DD statement for 
QSAfl files with RECORDING MODE V, S, 
or F. Specification of the T option 
is equivalent to including the APPLY 
RECORD-OVERFLOW option in the source 
program, but use of the T option in 
the DD statement allows the user to 
make his selection at object time. 



Figures 20 and 21 show the parameters in 
the DD statement that may be used with 
physical sequential files. All parameters 
except the DCB are described in "Job 
Control Procedures." Additional DCB 
subparameters not shown in the illustration 
are required for use with the Sort/Merge 
feature (see the chapter "Using the 
Sort/Merge Feature" for information on 
these parameters). 

The DCB subparameters that can be 
specified in the DD statement for physical 
sequential files are as follows: 



DCB=[ DEN= {0 J 1 J2J3J4} J 

[,TRTCH=tC| EJTJET} ] 
[,PRTSP={0| 112|3} ] 
[ ,M0DE={C}E} ] 
[,STACK={1|2| ] 
C,0PTCD={W1C1WC1TJQJZ} j 

[ ,BLKSIZE=integer ] 

[ ,BUFNO=integer ] 

[,EROPT=fACC|SKP| ABE} ] 

{ ,RECFM={F[VlUlD[B|S|T] [A|M] j] 

[,DIAGNS=TRACE] 

f ,FtJNC={I|RJPJW|0|XJT} ] 



DEN={0|1}2|3} 

can be used with m 
specifies a value 
recording density 
listed in Figure 1 
specified, 800 bit 
assumed for 7-trac 
bits- per- inch for 
dual density and 1 
for 9-track tape w 
depending on the i 
generic definition 



agnetic tape, and 

for the tape 

in bits per inch as 

9. If no value is 

s-per-inch is 

k tape, 800 

9-track tape without 

600 bits-per-inch 

ith dual density, 

nstallation's 

s for unit names. 
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DEN Values 









STACK={1|2} 

can be used with a card reader, a card 
punch, or a card-read punch, and it 
specifies which stacker bin is to 
receive the card. Either 1 or 2 is 
specified, if this information is not 
supplied by any source, 1 is assumed. 

STACK should not be used when the 
WRITE statement with the AFTER 
ADVANCING or POSITIONING option is 
used to specify pocket selection. 



TRTCH= {CJEJT JET} 

is used with 7-track tape to specify 
the tape recording technique, as 
follows: 

C - Specifies that the data-conversion 
feature is to be used; if data 
conversion is not available, only 
format F and format records are 
supported by the control program. 

E - specifies that even parity is to 
be used; if omitted, odd parity is 
assumed. 

T - Specifies that BCD to EBCDIC 
conversion is required. 

ET- specifies that even parity is to 
be used and BCD to EBCDIC 
conversion is required. 



DPTCD={H|CJT|QIZ} 

requests an optional service provided 
by the system as follows: 

W - To perform a write validity check 
(on mass storage devices only) . 

C - To process using the chained 
scheduling method (see the 
publication QS/ VS Data Management 
S ervices Guid e) . 

T - To request user totaling facility. 



Q - To translate to or from ASCII on 
tape 



Z - To request the search direct 

option (see the publication OS/VS 

Data flanagement Ser vices Guide ) . 



PRTSP={0 |1 |2|3} 

specifies the line spacing on a 
printer as 0, 1, 2, or 3. If PRTSP is 
not specified, 1 is assumed. 
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MODE={C]E} 

can be used with a card reader, a card 
punch or a card-read punch 
and specifies the mode of operation 
as follows: 

C - Specifies card image (column 
binary) mode. 

E - Specifies EBCDIC code. 

If this information is not supplied 
by any source, E is assumed. 



jjote: If the validity check is 
specified, the system verifies that 
each record transferred from main 
storage to mass storage is written 
correctly, standard recovery 
procedures are initiated if an error 
is detected. 



BLKSIZE= integer 

is used to specify the block size. 
This clause is used only when BiOCK 
CONTAINS RECORDS was specified at 
compile time. 

B0FNO=number of buffers 

is used to specify the number of 
buffers to be assigned to the file 
when neither the RESERVE nor the SAME 
AREA clause is specified for the file 
in the source program. The maximum 
number is 255. 

EROPT= (ACC JSKPJ ABE} 

specifies the options to be executed 
if an error occurs in writing or 
reading a record as follows: 

ACC - To accept the error block for 
processing. 
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SKP - To skip the error block. 

A3E - To terminate the job. 

There are two cases when the 
subparameter can be specified: 

• If no error processing declarative 
(OSE sentence) is specified, the 
option is taken immediately. 



If an error processing declarative 
is specified, the option is taken 
after the error declarative returns 
control via a normal exit (and only 
if that is the case) . 



If no option is specified, ABE is 
assumed. 

RECFM={FlVlUlD[B|S|T] [A|M]} 

specifies the format _ of~the 
records on the data set 
(see the JCL manual for the 
ways in which these individual 
subparameters can be combined) . 
Only the S and T subparameters 
have meaning for COBOL; COBOL 
ignores all others. 

F - records are of fixed length. 

V - records are of variable length. 

U - records are of undefined length. 

D - ASCII records of variable length, 

B - records are blocked. 



S - to expect the data set to consist 
of standard blocks. 

T - to use the TRACK OVERFLOW option 
(this specification has the same 
effect as including the APPLY 
RECORD-OVERFLOW option in the 
source program) . 

A - records contain ANS device control 
characters. 

M - records contain machine code 
control characters. 

DIAGNS=TRACE 

specifies the open/Close/EOV trace 
option which gives a module-by-module 
trace of Open/Close/EOV s work area 
and the DCB. The Generalized Trace 
Facility with the proper options 
specified must be active in the system 
while the job that requested the trace 
is running; the options are HODE=EXT 
and TRACE=0SS. 

F0NC=(I|B|P|fi|OfX|T} 

specifies the type of data set to be 
opened for the 3525 
Card-Read-Punch-Print as follows: 

I - interpret-punch data set. 

S - read 

p - punch 

W - print 

D - data protection for a punch data 

set 
X - printer 
T - two-line printer. 

For the valid combinations of these 

values see the publication OS/YS JCL 

Reference. 
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Figure 20. DD statement Parameters Applicable to Physical Sequential OUTPUT Files 
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Figure 21. DD Statement Parameters Applicable to Physical Sequential INPUT and i-o Files 



SPECIFYING ASCII FILE PROCESSING 



If a program will process an ASCII 
(American National Standard Code for 
Information Interchange) QSAH file, the 
user must identify it as such in one of two 
ways. One technique is to use the CODE- SET 
pjhrase of the COBOL FD stateient to 
reference an alphabet-name that was defined 
as STANDARD- 1 (which is equivalent to 
ASCII). The other technique is to use the 
COBOL ASSIGN clause, with assignment-name 
having the following format: 



buffer offset 

a two-character field that indicates 
the length of the bloc It prefix for 
that file. This entry is required if 
a non-zero block prefix exists; it 
must, however, be omitted when an 
ASCII-collated sort is requested. 



name 



a field of 1 to 8 characters that 
specifies the system-recognized name 
of the file. It is this external name 



comment-C- (buffer offset) -name 



where : 



an organization code which specifies 
that an ASCII-encoded sequential file 
is to be processed, or that an 
ASCII-collated sort is to be 
performed. 
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that appears in the name field of the 
DD card for the file. 

If this ASSIGN technique is used, 
LANGLVL ( 1 ) must be specified. 



PROCESSING ASCII FILES 



Record format allowed for ASCII files 
are the following: mode F (fixed length) , 
mode U (undefined) , and mode D (variable 
length. D-mode records are of variable 
length with a four-byte record descriptor 
field for each record. The COBOL 
programmer processing variable-length 
records specifies V-mode records. Then the 
format information generated from the DCB 
parameter is internally converted to D 
mode. Format-D records cannot be 
explicitly specified by the user in a COBOL 
program. 



Block Prefix 



An ASCII file may have a variable-length 
field, called a block prefix , preceding the 
first logical record in a physical record. 
If this prefix exists on an ASCII file, its 
length must be indicated at compile time in 
the buffer offset field of the ASSIGN 
clause. The compiler places this length in 
the DCB parameter at compile time. 

Whether the optional block prefix 
contains the block length or simply user 
information depends on the type of file 
specified (input or output) and the 
internal record mode ( i.e. , F, U, or D) . 
These distinctions are made in the 
discussion that follows. 

Files Opened as Input : Input files with 
either blocked or unblocked records have an 
optional block prefix of to 99 bytes that 
does not contain the block length but may 
contain user information. For D-mode 
records, however, a block prefix of length 
four may contain the block length. 
Regardless of the record format, file 
processing is identical to that for files 
coded in EBCDIC. 

Files Opened as Output : The block prefix 
for output files applies only to D-mode 
records and, when specified, must have a 
length of 4 . The prefix must contain the 
length of the block, which length includes 
the buffer offset. 

For any ASCII output file the ASSIGN 
clause may include a buffer offset of four. 
Alternatively, the programmer may omit this 



specification from the ASSIGN clause, 
instead making use of the phrase BLOCK 
CONTAINS RECORDS. The offset can then be 
specified at execution time in the JCL. 
However, if BLOCK CONTAINS RECORDS is 
used, the following options must be 
included in the JCL: 



BUFOFF=(n) 

must be included in the DCB parameter 
of the DD card, where n is the length 
of the block prefix from to 99 
characters on input, and either or 4 
on output. 



BLKSIZE=(n) 

must be included on the DD card, where 
n is the size of the block, including 
the length of the block prefix. 



Notes : 

• If a block prefix exists on an ASCII 
file and the BLOCK CONTAINS clause with 
the CHARACTERS option is used, the 
length of the block prefix must be 
included in the BLOCK CONTAINS clause. 

. If either the RECORDS option is 
specified or the BLOCK CONTAINS clause 
is omitted, the compiler compensates 
for the block prefix (if specified) . 

Additional JCL considerationa for ASCII 
data sets follow. 



LABEL= 



where AL specifies American National 
Standard labels, AUL specifies American 
National Standard and user labels, and NL 
indicates no labels. 

The subparameters below are specified in 
the DCB parameter of the DD statement: 

OPTCD=Q, where Q specifies an ASCII-encoded 
data set. 

RECFM=D, where D represents a 

variable-length record, is an optional 
parameter. Whether or not this 
parameter is specified at execution 
time, the programmer must specify an 
ASCII file in the ASSIGN clause as 
well as a mode-V record. The compiler 
converts from mode V to mode D, or to 
the internal representation for a 
variable-length record. 

BUFOFF=(L) , where L indicates a four-byte 
block prefix that contains the block 
length including the block prefix. 
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Handling. Numeric Da ta. Itemg^frQm ASCII 
Files 



It is highly recommended that the 
programmer take advantage of the separately 
signed numeric data type. The SIGN clause 
(see "SIGN clause" in the chapter 
"Programmer Considerations") can be used to 
specify the position and the mode of 
representation of the operational sign of 
numeric data items. 



• Reco rd Identifier 

The remainder of data-name, which is 1 
through 255 bytes in length, is the 
record identifier. It represents the 
symbolic portion of the key field used 
to identify a particular record on a 
track. 



The following example illustrates the 
use of the ACTUAL KEY clause: 



DIRECT FILE PROCESSING 



The direct file proce 
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ENVIRONMENT DIVISION. 



ACTUAL KEY IS THE- ACTU AL-KEY. 



DATA DIVISION. 



WORKING-STORAGE SECTION. 
01 THE-ACTUAL-KEY- 

05 TRACK-IDENT PIC S9 (5) COHPSYNC. 

05 RECOSD-IDENT PIC X{25). 



Note: The same record identifier may 
appear more than once in the same file when 
using COBOL. However, using the same 
record identifier is not recommended for 
the following reasons: 



Format 



»- 



I 

1 ACTUAL KEY IS data-name 

J 



1. If they appear on the same track, only 
the first occurrence can be retrieved 
(using BDAM) . 



Data-name may be any fixed item from 5 
through 259 bytes in length and must be 
defined in the File Section, Working- 
Storage Section, or Linkage Section. The 
following considerations apply when 
defining the ACTUAL KEY: 

* Track Ident ifier 

The first four bytes of data-name are 
the track identifier. The identifier 
is used to specify the relative track 
address for the record and must be 
defined as a 5-integer binary data item 
whose maximum value does not exceed 
65,535. 



If an extended search is used in 
either creating or updating a file, 
the position of records containing 
duplicate record identifiers may be 
unpredictable. 



With direct file processing, records 
must be unblocked and may be V-, U-, F-, or 
S-mode records. Figure 22 illustrates 
those parts of a directly organized file 
that are of importance to a COBOL 
programmer. 
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Figure 22. Directly Organized Data as it Appears on a Mass Storage Device 



Each track contains the following: 



Index Point 

There is one index point to indicate 
the physical beginning of each track. 



Gaps separate the different areas on 
the track. Certain equipment 
functions take place as the gap is 
rotating past the read/write head. 
The length of the gap varies with the 
device, the location of the gap, and 
the length of the preceding area. For 
instance, the gap that follows the 
index point is a different length than 
the gap that follows the track 
address. 



key area — 



data area — 



the- record identifier 
(1-2 55 bytes) as 
specified by the 
programmer in the ACTUAL 
KEY clause. 



the- data moved into the 
FD before a HRITE 
statement was executed. 



The following example illustrates the 
relationship between the ACTUAL KEY and the 
positioning of records on a mass storage 
device during the creation of a direct 
file. 



lEaS k Addr es s 

This field defines the physical 
location of the track. It indicates 
the cylinder in which the track is 
located and the read/ write head that 
services the track. 



SO {Cap a city Recor d) 

This field indicates the amount of 
unused space available for additional 
records on the track. 



HI, R2. 



■ If t,« ■ S" 



Sn 



These are physical records that 
contain the following: 



ENVIRONMENT DIVISION. 



ACTUAL KEY IS THE- ACTUAL-KEY. 



DATA DIVISION. 
FILE SECTION. 
FD DIRECT-FILE 

LABEL RECORDS ARE STANDARD. 
01 REC-1 PIC X(200) 



WORKING-STORAGE SECTION. 
01 THE- ACTUAL-KEY. 

05 TRACK-IDENT PIC S9(5) COMP SYNC. 

05 RECORD-IDENT PIC X (3) . 



count area — control information 
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T8ACK 



count Key Data 



Count Key Data 



I 1 % T 

6 ] |AAAJREC-1| G | 
i 1 »_____J *_ 



Count Key Data 



|CCCJ8EC-1| G J 

J_ 1 J 4. 



T I 1 

|BBB|BEC-1| 
~i i i 



TBACK 1 



G 1 



JDDDf REC-1 | G I 

_L- I ■ ,,l i- 



|FFF|REC-1J G J 

.4 J J L 



|EEE|BEC-1} 



Figure 23. Sample Format of the First Two Tracks of a Direct File 



Consider REC-1 being written six times; the 
contents of THE- ACTUAL-KEY varying with 
each WBITE instruction: 



THE-ACTUAL-KEY 



TBACKJ RECORD 
IDENTIIDENT 
H 1 



WRITE 
WRITE 
WBITE 
WBITE 
WRITE 
WRITE 



i 

1 o 

J — 



) AAA) 
4 i 



J 

I 



1 CCCJ 

H 1 



I BBBJ 



| 1 ] DDDi 
I J 1 



I 1 



I 1 
i 



I FFFJ 
4 i 



I SEE) 
_i j 



fielative track and relative track 1 of 
the mass storage device will appear as 
shown in Figure 23. 



When the WRITE statement 
the system seeks the track t 
to the number contained in T 
then searches for the next a 
position into which a record 
The system writes a count ar 
contents of RECORD-IDE NT in 
and writes the information c 
REC-1 in the data area. 



is executed, 
hat corresponds 
RACK-IDENT. It 
variable 

may be placed, 
ea, writes the 
the key area, 
ontained in 



Note: The record identifier is not 
included in the level-01 record description 
(REC-1). It will, however, be moved into 
the output buffer before being written on 
the mass storage device. Buffer areas, 
therefore, will be large enough to 
accommodate both the contents of REC-1 and 
the record identifier. 



tnd, Capacity, R ecords 



Once a direct file has been created, 
records can be added randomly on tracks 
formatted seguentially. Unless a track is 
already filled with data records, it is 
formatted by the compiler via the writing 
of dummy records (mode F) or of one 
capacity record (node U, V, or S) . 



In order to format tracks, a COBOL 
subroutine executes instructions to write 
dummy records for F-mode files or write 
capacity records for V~, U-, or s-mode 
files. Dummy records are identified by the 
presence of the figurative constant 
HIGH-VALUE in the first byte of the record 
identifier portion of the ACTUAL KEY 
(unless changed by the program collating 
sequence, in which case the byte contains 
X»FF*) . This indicates to the system that 
a record can be added to the file in the 
space assigned to the dummy record. (The 
user should not attempt to retrieve a dummy 
record by moving this configuration to the 
record identifier because it is considered 
an invalid key.) A capacity record is a 
single record at the physical beginning of 
each track that indicates the amount of 
space available for additional records. As 
V-, U- , or S-mode records are added to a 
track, the capacity record is written 
accordingly. Capacity records are never 
made available to the user. 

When a file is created, it should 
contain enough dummy records, or 
appropriately written capacity records, to 
allow for future expansion. Once the file 
is closed, more space cannot be allocated 
and the extent of the file cannot be 
increased. 



Note : Tracks that have been assigned to a 
file but are not formatted, are considered 
"allocated." The user should not attempt 
to write on tracks that have been allocated 
but not formatted. 
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Seq u ential Creatio n of Direct Data Set 



The file processing technique used to 
create a direct file sequentially is BSAM 
(Basic Sequential Access Hethod) . 

• The associated COBOL statements are 
summarized in Figure 31. 

• The associated JCL parameters are 
summarized in Figure 3 2. 



The ACTUAL KEY is required. It 
specifies the relative track number on 
which the record is to be written. Since 
access is sequential, all records will be 
written serially in the sequence in which 
they are moved into the output buffer. It 
is, therefore, necessary that all records 
to be written on the first track (track 
identifier = 0) be processed before records 
to be written on the 2nd, 3rd, ..., nth 
track (track identifier = 1, 2, ..., n-1) 
are processed. 

When records are written sequentially, 
the user need not update the contents of 
the track identifier portion of the ACTUAL 
KEY. A COBOL subroutine will update it as 
follows: 

• Records will be written on the first 
available track until space is no 
longer available. At such time, the 
COBOL subroutine will increment the 
track identifier by 1, and continue 
writing on the next track. 

• The value of track identifier used by 
the system is made available to the 
user in the track identifier portion of 
the ACTUAL KEY after the record is 
written. 

» After a CLOSE or CLOSE UNIT statement 
has been executed, the COBOL subroutine 
places the relative track number of the 
last track written on (for a data, 
dummy, or capacity record) in the track 
identifier of the ACTUAL KEY. 

• If the user updates the contents of 
track identifier and attempts to write 
on track 2 when tracks through 4 are 
already full, the systeia will 
automatically adjust the track 
identifier to 5 (the next track with 
available space) . 



If the user wishes to skip tracks, the 
number of tracks, equal to the number of 
tracks to be advanced, must be added to the 
track identifier. The COBOL subroutine 
will then add dummy records (F-mode) or 
write capacity records (V-, U-, or S-mode) 



to complete the intervening track (s) (see 
"Dummy and Capacity Records") . If the 
value of track identifier for the initial 
WRITE is not 0, the subroutine will 
complete the preceding tracks with dummy or 
capacity records. 



gPACB, ALLOCATieM-gQR- SIlfGtg- VOLUME FILES: 
When a file is created sequentially, the 
number of primary tracks specified on the 
DD card must be available on the primary 
volume. If this quantity is not available, 
the job will not beqin execution. Once 
execution begins however, the final 
allocation of space will not be made until 
the file is closed. 



The following discussion illustrates the 
space allocated to a direct file created 
using BSAM. Figure 24 is an example of a 
user program that: 



• Writes 350-1/2 tracks and then closes 
the file. 

• Specifies SPACE= (TRK, (200, 100) ) on the 
associated DD card. 

TRACK-LiaiT-Claase Specified : 

1. If the TRACK-LIMIT clause specifies 
TRACK-LIMIT = 499 and the file is 
closed after writing only 350-1/2 
tracks: 

Mote; A COBOL subroutine will format 
all remaining tracks up to and 
including the 500th track. This 
represents 150 extra tracks on which 
records may be added. 

2. If the TRACK-LIHIT clause specifies 
TRACK-LIMIT = 300 and the program 
continues writing all 350-1/2 tracks: 

Note: The TRACK-LIMIT clause is 
ignored and the system allocates and 
formats as if no TRACK-LIMIT clause 
had been specified. 



TRACK-LIMI T Cl au se Sot Specified: If the 
TRACK-LIMIT clause is not specified, the 
system will allocate the primary extent 
(i.e., 200 tracks) and up to 16 secondary 
extents (i.e., 100 tracks each) , as 
required. In Figure 24, the system 
allocates the first 200 tracks, all of 
which are completed. The second 
allocation, of 100 tracks, is also 
completed. The next 100-track allocation 
is, however, only partially used. The file 
is closed after writing on 350-1/2 tracks. 
At this time: 
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A COBOL subroutine will format the rest 
of the 351st track. <Note that 351 
tracks are actually relative tracks 
through 350) 

The balance of 49 tracks will remain 
allocated but will not be formatted. 



No^®* In some of the foregoing cases, the 
number of tracks allocated to the file 
exceeds the number of tracks formatted by 
the COBOL subroutine. If the excess space 
was requested in track or block units, it 
should be released by specifying the ELSE 
option of the SPACE parameter. 



Specified as TRACK-LIMIT=499 



TRACK-LIMIT Clause Not Specified 



written on 
formatted 



formatted { 



r* 

J 

I 

\ 200 

I 

f 

I 
I 
1 100 

I 

I 51 

H 

| 49 



I 100 



J 
J 



nst allocation 

(2nd allocation 
>3rd allocation 
4th allocation 



J 

] un used 



r K 



written on 
and/or 

formatted 



unformatted ( 



200 



100 



51 



49 



unused 



1st allocation 



2nd allocation 



3rd allocation 




N otes : 

1. SPACE=(TBK, {200,100}) on a single volume. 

2. The user program writes 350-1/2 tracks before closing the file. 

i 

Figure 24. Sample Space Allocation for Sequentially Created Direct Files 
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Specified as 
TRACK-LIMIT=949f- 




formatted 
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clause not 
specified 
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formatted 
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i \ 

| unused \ 



Wv\J 



formatted 



\ 



SPACE=(TRK, (300,100)} on Volumes A, B, and C 



Figure 25. Sample Space Allocation for Randomly Created Direct Files 



Ra ndom Cr eation of a Direct , Data_get 



The file processing technique used to 
create a direct file randomly is BDAM 
(Basic Direct Access Method) . 



• The associated COBOL statements are 
summarized in Figure 31. 



» The associated JCL parameters are 
summarized in Figure 32. 



Figure 30 (sample program) illustrates 
the random creation of a direct data set. 



The ACTUAL KEY is required. when a 
direct file is created randomly, records 
need not be written in any particular 
sequence. The system seeks the track 



specified in the track identifier portion 
of the ACTUAL KEY and writes the record in 
the next available position on that track. 



When a file is created using BDAM, the 
number of tracks specified in the primary 
extent must be available on the primary 
volume. If there are secondary volumes, 
one secondary extent must be available on 
each of the secondary volumes. If these 
extents are not available, the job will not 
begin execution. Once execution begins, 
the final allocation of space is determined 
by the TRACK-LIMIT clause and the SPACE and 
volume-count parameters of the DD card when 
the file is opened as an output file. 
Figure 25 illustrates the allocation and 
formatting of space when the TRACK-LIMIT 
clause is specified as well as when it is 
not specified fsee "Dummy and Capacity 
Records" for a definition of alloc ate and 
format) . 
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1- When a TRACK-LIMIT clause is specifed 
(Figure 25) , the system Mill do the 
following: 

a. Allocate tracks, by blocks, until 
the quantity specified by the 
TRACK- LIMIT clause has been 
egualed or just exceeded. 

b. Format only the space specified in 
the T8ACK-LIMIT clause, even if 
the space formatted is less than 
the space allocated. 

2. Shen a TRACK-LIMIT clause is not 
specified (Figure 25) , the first 
volume will be allocated and formatted 
according to the primary allocation 
quantity, and any succeeding volumes 
will be allocated and formatted from 
the secondary quantity, one quantity 
per volume. 



Records cannot be written on those 
tracks that were allocated but unformatted. 
Any attempt to do so will have 
unpredictable results. Unformatted tracks 
can be released by specifying the 8LSE 
option in the SPACE parameter on the 
corresponding DD statement. Only space 
requested in track or block units can be 
released. If the CYL subparameter was 
specified, the unformatted tracks cannot be 
released. 

Unlike direct files created with BSAM, 
the BDAM processing technique allocates and 
formats tracks when the file is opened. 
This is significant because the system will 
not allocate secondary extents if the user 
attempts to write on more tracks than the 
quantity initially formatted. 

Note; The extended search option may be 
used during random creation. See "Random 
Reading, Updating, and Adding to Direct 
Data Sets" for a detailed description. 



Sequential R eadin g of Direct Data Sets 



The file processing technique used to 
read a direct file seguentially is BSAM 
(Basic sequential Access Method) . 

• The associated COBOL statements are 
summarized in Figure 31. 

• The associated JCL parameters are 
summarized in Figure 32. 



Shen a direct file is being read 
sequentially, records are retrieved in 
logical sequence. This logical sequence 



corresponds exactly to the physical 
sequence of the records on the mass storage 
device. Dummy records, if present, are 
also made available. 

For reading a file seguentially, the 
ACTUAL KEY clause need not be specified; 
however: 

• If the key is not specified, the user 
will have no way of distinguishing 
between real and dummy records (F-mode 
only). Dummy records can be recognized 
by testing for the presence of the 
figurative constant "HIGH VALUE" in the 
first position of the record 
identifier. 

* If the ACTUAL KEY clause is specified, 
the record* s key will be placed in the 
record identifier portion of the ACTUAL 
KEY during the execution of a READ 
statement. The track identifier, 
however, remains unchanged. 

Random Rea ding . Updating, and Adding_.tg 
Direct Data Sets 

The file processing technique used to 
read, update, and add to a direct file 
randomly is BDA!? (Basic Direct Access 
Method) . 

• The associated COBOL statements are 
summarized in Figure 31. 

* The associated JCL parameters are 
summarized in Figure 3 2. 

When records are being retrieved from a 
direct file randomly, the ACTUAL KEY is 
required to determine the track and to 
locate a particular record on that track. 
When a match is found, the data portion of 
the record is read. For an add operation, 
after locating the track, the system 
searches for the next available position on 
the track, and writes the new record. For 
an update operation, after locating the 
track, the system searches for the record 
specified in the record identifier portion 
of the ACTUAL KEY. (Note. A record in 
variable length BDAM files can be updated 
only with a record of the same length.) 

In all of the foregoing cases, the 
specified track is the only one searched. 
If the desired record cannot be found, or 
room for an additional record cannot be 
found, the search terminates with an 
INVALID KEY condition. If the user wishes 
to extend the search to a specific number 
of tracks or to the entire file, the DCB 
OPTCD and LIMCT subparameters should be 
specified on the corresponding DD card. 
(Figure 30 illustrates the use of extended 
search.) 
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Mult ivolume 



Multivolume data sets, like 
single-volume data sets, may be created 
either randomly or sequentially. 



Sequ ential Creatio n; When a 
created sequentially, the nu 
specified in the primary ext 
available on the primary vol 
number of tracks specified i 
extent must be available on 
secondary volumes. If ext en 
available, execution of the 
begin. Once execution begin 
and as many secondary alloca 
possible, are given to the f 
to 16 extents per volume), 
volumes are allocated from t 
specification. 



file is 
mber of tracks 
ent must be 
ume and the 
n the secondary 
each of the 
ts are not 
job will not 
s, the primary, 
tions as 
irst volume (up 
Subsequent 
he secondary 



If the CLOSE UNIT statement is executed, 
the current extent is formatted, volume 
switching procedures are executed, and the 
contents of ACTUAL KEY are updated to 
reflect the relative track number of the 
last track on the old volume. This is 
illustrated in the following example. 

Consider the creation of a multivolume 
file whose space is allocated by: 

SPACE=(TRK, (300, 100)) 

1. When execution begins, the system 
allocates 300 tracks on the first 
volume. When the 300 tracks are used 
up, the system allocates 100 tracks 
more. Up to 16 allocations of 100 
tracks each are possible. 

2. If, after writing on 45 tracks, a 
CLOSE UNIT statement is executed, a 
COBOL subroutine will format the 
remaining 50 tracks of the current 
allocation before making the next unit 
available. 

3. After the CLOSE UNIT statement is 
executed, a COBOL subroutine places 
the relative track number of the last 
track written on (for a data, dummy, 
or capacity record) in the track 
identifier of the ACTUAL KEY. 



Note: A CLOSE UNIT stat em 
formats the tracks remain! 
from the current allocatio 
formatting of tracks on th 
a CLOSE file-name statemen 
depends on the presence or 
TRACK-LIMIT clause, just a 
single-volume files (see M 
for Single- Volume Files") 
option of the SPACE para me 
to the unformatted tracks 
last unit. 



ent always 
ng on that unit 
n. The 

e last unit, when 
t is executed, 
absence of a 
s it did for 
Space Allocated 
. The ELSE 
ter applies only 
at the end of the 



Automatic Volume Switchin g: The user may 
choose to permit volume switching to occur 
automatically. This can be accomplished by 
writing on all allocated tracks until no 
more are available, or may be made 
available. This procedure, however, does 
not guarantee a specific distribution of 
records over the volumes, the placement of 
a particular record on a particular volume, 
or whether the data set is, in fact, 
multivolume. 

Note : If the user permits system 
controlled volume switching, but specifies 
the file be created on more than one volume 
[e.g., VOL=SER=(V1,V2,V3) ]; the system may 
write the entire file on the primary volume 
if there is enough room. The next time an 
attempt is made to open that file, since 
the system expects it to reside on three 
volumes, an ABEND will occur. This can be 
avoided by specifying: 

VGL= (, , , 3, SER= (V 1 , V2, V3) ) 

This specifies the file be contained on one 
or rnor e volumes. 



To create a file with records 
distributed as evenly as posible over 
several volumes, the programmer must 
calculate the amount of space his file will 
require (see "Determination of File Space") 
and divide by the number of volumes. The 
result of this calculation (rounded) should 
be specified as both the primary and 
secondary allocation of the SPACE parameter 
of the associated DD statement. The 
programmer should execute CLOSE UNIT before 
the end of the initially allocated space on 
the first volume (that is, execute the 
CLOSE UNIT before writing the record that 
is to be first on the second volume) . 



For example, to distribute 2232 132-byte 
records as evenly as possible on two 2314 
volumes, 37 tracks per volume are required 
and the SPACE parameter should specify 
(37,37). After writing the 1116th record 
the programmer should execute CLOSE UNIT 
and continue writing. 

If the required space is overestimated 
and the records do not fill the last 
track (s) , the compiler will write dummy 
records to complete them. These records 
are included in the record count and should 
be taken into account when trying to 
address records on subsequent volumes. 

If the space required is underestimated, 
automatic volume switching may occur before 
the CLOSE UNIT is executed since space on 
the first volume is filled. If this has 
happened, the CLOSE UNIT starts a third 
volume. 
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If no secondary allocation has been 
specified and the program issues a CLOSE 
UNIT statement, the job will terminate 
abnormally, since the allocation of 
subsequent volumes is taken from the 
secondary allocation field of the SPACE 
parameter. 

In the creation of an output file, 
performance is improved by specifying the 
CONTIG subparameter of the SPACE parameter 
in the DD statement. However, space 
allocation is more efficient if CONTIG is 
not specified. 



£J3-.g;,.Qj^gas4si£i9B..,Ii§irJi g£ -the System- Name 



The single character W D" or "W M , 
specifying the file organization, must be 
coded as part of the system- name. The user 
should be aware of the following 
differences: 



• Sequentially accessed files must specify 
organization "D". 



Rand om C reation: when a file is created 
randomly, space allocation and formatting 
is done as described in "Random Creation of 
a Direct Data Set" (Figure 25). It is 
important to note that a CLOSE UNIT 
statement is not permitted when creating a 
file randomly. 



The following description pertains to 
Figure 25: 

1. When the TRACK-LIMIT clause is 

specified, the total extent of the 
file is 950 tracks. The only valid 
track identifiers are through 949: 

* Tracks 000 through 499 are contained 
on volume A. 

♦ Tracks 500 through 89 9 are contained 
on volume B. 

• Tracks 900 through 949 are contained 
on volume C. 



» Randomly accessed files may specify "D" 
or "i". When opened input or output M D" 
and "W" function identically. 



1. Opened output ("D" and •»»«) : 

WRITE adds a new record, If a 
record containing the same key 
already exists, the system will add 
the record anyway. The result will 
be records with duplicate keys. 



2. Opened 1-0 {"»"} : 

a. REWRITE automatically searches 
for a record with a matching 
record identifier, and updates 
it. 

b. WRITE adds a new record to the 
file whether or not a duplicate 
key already exists. 



When the TRACK-LIMIT clause is not 
specified, the total extent of the 
file is 500 tracks. The only valid 
track identifiers are through 499: 

* Tracks 000 through 299 are contained 
on volume A. 

» Tracks 300 through 399 are contained 
on volume B. 

* Tracks 400 through 499 are contained 
on volume C. 



3. Opened 1-0 ("D") : 

a. REWRITE updates the file only if 
the preceding input/output 
statement was a READ of the same 
record. 

b. WRITE adds a new record to the 
file, whether or not a duplicate 
key already exists, if the 
preceding input/output statement 
was anything other than a READ 
of the same record. 
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Note: When a file is opened 1-0 (BDAM 
"D") the contents of ACTUAL KEY are 
moved to a save area during the 
execution of a READ statement. During 
the execution of a WHITE statement, the 
contents of ACTUAL KEY are compared to 
the contents of the save area to 
determine whether the system should add 
or update a record. A check is also 
made to assure that the preceding 
input/output statement was a READ. If 
it was a WRITE of any record, a new 
record is added to the file, opening a 
file 1-0 (BDAM "W") omits the save and 
compare steps entirely. The system adds 
a record when a WRITE statement is 
executed and updates a record when a 
REWRITE statement is executed. It is, 
therefore, more efficient to use BDAM 
"»" than it is to use BDAM "D" if it is 
Known in advance whether the record 
should be added or updated. 



Dete rmin ation of File space; To determine 
the amount of space a data set requires, 
the following variables should be 
considered: 

Device Type 
Track Capacity 
Tracks per Volume 
Cylinders per Volume 
Data length (block size) 
Key Length 
Device Overhead 



Device ov 
required on 
i.e., addres 
inter-record 
overhead var 
depends on w 
with keys, 
be used to c 
reguired for 
overhead. 



erhead refer 
each track f 
s markers, c 

gaps, Recor 
ies with eac 
hether the b 
The formulas 
orapute the a 

each block, 



s to the space 
or hardware data, 
ount areas, 
d 0, etc. Device 
h device and also 
locks are written 

in Figure 26 may 
ctual space 

including device 



Figure 27 lists device storage capacity, 
and Figure 28 lists capacity in records per 
track for several mass storage devices. 

Programmers who require more detailed 
information on mass storage devices may 
refer to the IBM System/370 System Summary. 
Order No. GA22-7001. 



Note: Specification of the "S" option in 
the DCB subparameter RECFM can increase 
3330 performance (see the description of 
RECFM earlier in this chapter) . 



Ra ndomizing Technique s 



One method of determining the value of 
the track identifier portion of the ACTUAL 
KEY is called indirect addressing. 
Indirect addressing generally is used when 
the range of keys for a file includes a 
high percentage of unused values. For 
example, employee numbers may range from 
000001 to 009999, but only 3000 of the 
possible 9999 numbers are currently 
assigned. indirect addressing can also be 
used with nonnumeric keys. A nonnumeric 
field (e.g., alphanumeric) , when moved to c 
computational field, will be packed and 
then converted to binary notation. Since 
packing eliminates the zone fields, the 
final binary item will be numeric. 



Indirect addressin 
is converted to a val 
identifier by use of 
intended to limit the 
Such an algorithm is 
technique . Random izi 
produce a unique addr 
in fact, such techniq 
synony ms. Synonyms a 
randomize to the same 



g means that the key 
ue for the track 
some algorithm 

range of addresses, 
called a randomizing 
ng techniques need not 
ess for every record; 
ues usually produce 
re records whose keys 

address. 



Two objectives must be considered in 
selecting a randomizing technique: 

1. Every possible key in the file must 
randomize to an address within the 
designated range. 

2. The addresses should be distributed 
evenly across the range so that there 
are as few synonyms as possible. 



Note that one way to minimize synonyms 
is to allocate more space for the file than 
is actually required to hold all the 
records. For example, the percentage of 
locations actually used might comprise only 
80 to 85 percent of the allotted space. 
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Division/Remainder Metho d: One of the 
simplest nays to address a directly 
organized file indirectly is to use the 
division/remainder method. 

1. Determine the amount of locations 
required to contain the data file. 
Include a packing factor for 
additional space to eliminate 
synonyms. The packing factor should 
be approximately 20 percent of the 
total space allotted to contain the 
data file. 

2. Select the nearest prime number that 
is less than the total of step 1. k 
prime number is a number divisible 
only by itself and the integer 1. 
Figure 29 is a partial list of prime 
numbers. 

3. Clear any zones from the key that is 
to be used to calculate the track 
identifier of actual key. This can be 
accomplished by moving the key to a 
field described as COMPUTATION&t. 

4. Divide the key by the prime number 
selected. 

5. Ignore the quotient; utilize the 
remainder as the relative location 
within the data file. 



For example, assume that a company is 
planning to create an inventory file on a 
2314 disk storage device. There are 8,000 
different inventory parts, each identified 
by an 8-character part number. Using a 20 
percent packing factor, 10,000 record 
positions are allocated to store the data 
file. 



Met hod A ; The closest prime number to 
107000, but under 10,000, is 9973. Using 
one inventory part number as an example, in 
this case #25DF3514, and clearing the 
zones, we have 25463514. Dividing by 9973 
a quotient of 2553 results in a remainder 
of 2445. Thus, 2445 is the relative 
location of the record within the data file 



corresponding to part number 25DF3514. The 
record address can be determined from the 
relative location as follows: 

1. Determine the number of records that 
can be stored on a track (e.g., 13 per 
track on a 2314, assuming each 
inventory record is 200-bytes long) . 

No te : Because each data record has 
nondata components, such as a count 
area and inter-record gaps, track 
capacity for data storage will vary 
with record length. As the number of 
separate records on a track increases, 
inter-record gaps occupy additional 
byte positions so that data capacity 
is reduced. Track capacity formulas 
provide the means to determine total 
byte requirements for records of 
various sizes on a track {see Figures 
26-28) . 

2. Divide the relative number (2445) by 
the number of records to be stored on 
each track. 

3. The result, quotient = 188, now 
becomes the track identifier of the 
actual key. 



Method B: Utilizing the same example, 
another approach will also provide the 
relative track address. Method B is 
illustrated in Figure 30: 

1. The number of records that may be 
contained on one track is 13. 
Therefore, if 10,000 record locations 
are to be provided, 770 tracks must be 
reserved. 

2. The prime number nearest, but less 
than 770, is 691. 

3. Divide the zone-stripped key by the 
prime value. (In the example, 
25463514 divided by 691 provides a 
quotient of 36850 and a remainder of 
164. The remainder is the track 
identifier.) 
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Figure 26. Mass Storage Device Overhead For aulas 
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Figure 27. Mass Storage Device Capacities 
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Figure 28. Hass storage Device Track Capacity 
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00001 
00002 
00003 
00004 

C0005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
00014 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00020 
00025 
00026 
00027 
00028 
00029 
00030 
00031 
00032 
00033 
00030 
00035 
00036 
00037 
00038 
00039 
00040 
00041 
00042 
00043 
00044 
00045 
00046 
00047 
00048 
00049 
00050 



00101 
00102 
00103 
00104 
00105 
00106 
00107 
00108 
00109 
00110 
00112 
00113 
00114 
00115 
00116 
00117 
00118 
00119 
00120 
00121 
00122 
00201 
00202 
00203 
00204 
00205 
00206 

00207 
00209 
00210 
00211 
00212 
00213 
00214 

00303 
00304 
00305 
00306 
00307 
00308 
00309 
00310 
00311 
00312 
00313 
00314 
00315 
00316 



<2) 



IDENTIFICATION DIVISION. 
PROGRAM-ID. METHOD B. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM- 370. 
OBJECT-COMPUTER. IBM- 370. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT D-FILE ASSIGN DA-2314-D-MASTER 

ACCESS IS RANDOM ACTUAL KEY IS ACT-KEY 

TRACK-LIMIT IS 691.-« — 

SELECT C-FILE ASSIGN UT-S-CARDS. 
DATA DIVISION. 
FILE SECTION. 
FD D-FILE 

LABEL RECORDS ARE STANDARD. 
01 D-REC. 

02 PART-NUM PIC X(8). 

02 NUM-ON-HAND PIC 9(4). 

02 PRICE PIC 9<5)V99. 

02 FILLER PIC X(181). 
FD C-FILE 

LABEL RECORDS ARE OMITTED. 
01 C— REC 

02 PART-NUM PIC X(8). 

02 NUM-ON-HAND PIC 9(4). 

02 PRICE PIC 9(5)V99. 

02 FILLER PIC X(61). 
WORKING-STORAGE SECTION. 
77 SAVE PIC S9(8) COMP SYNC. 
77 QUOTIENT PIC S9(5) COMP SYNC. 
01 ACT-KEY. 

02 TRACK- ID PIC S9(5) COMP SYNC. 

02 REC-ID PIC X(8). 
PROCEDURE DIVISION. 

OPEN INPUT C-FILE OUTPUT D-FILE. 
READS. 

READ C-FILE AT END GO TO EOJ. 

MOVE CORRESPONDING C-REC TO D-REC. 

MOVE PART-NUM OF C-REC TO REC-ID SAVE. 

DIVIDE SAVE BY 691 GIVING QUOTIENT REMAINDER TRACK-ID. -*- 
WRITES. 

EXHIBIT NAMED TRACK- ID C-REC. 

WRITE D-REC INVALID KEY GO TO INVALID-KEY. 

GO TO READS. 
INVALID-KEY. 

DISPLAY • INVALID KEY • TRACK- ID REC-ID. 
EOJ. 

CLOSE C-FILE D-FILE. 

STOP RUN. 



<D 



Figure 30. Sample Program for a Randomly Created Direct File (Part 1 of 2) 
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0C0010 IKF8003I-W RANDOM OPTION OF ACCESS MODE IS CLAUSE IS AN EXTENSION TO LEVEL A. 

000010 IKF8003I-W ACTUAL KEY IS CLAUSE IS AN EXTENSION TO LEVEL A. 

000011 IKF8002I-W TRACK-LIMIT CLAUSE IN SELECT SENTENCE IS AN EXTENSION TO ALL LEVELS. 

000039 IKF8003I-W CORRESPONDING OPTION IS AN EXTENSION TO LEVEL A. 

000040 IKF8003I-W QUALIFICATION OF DATA-NAMES AND PARAGRAPH- NAMES IS AN EXTENSION TO LEVEL A. 
C 00041 IKF8003I-W REMAINDER IN DIVIDE STATEMENT IS AN EXTENSION TO LEVEL A. 

000043 IKF8002I-W EXHIBIT STATEMENT IS AN EXTENSION TO ALL LEVELS. 

C00047 IKF8002I-W APOSTROPHE USED AS QUOTE IS AN EXTENSION TO ALL LEVELS. 

C00049 IKF8003I-W USE OF MULTIPLE FILE-NAMES IN CLOSE STATEMENT IS AN EXTENSION TO LEVEL A. 



FIPS messages 
for LVL=A 



XXGO EXEC PGM=*.LKED.SYSLMOD,COND=((5,LT # COB) , (5,LT,LKED)) 

XXSTEPLIB DD DSN=VSCBL1.LIB,DISP=SHR,UNIT=2314 ,VOL=SER=DB143 

XXDD1 DD DSN=6SYMDBG,DISP=(OLD, DELETE) 

XXSYSDBOUT DD SYSOUT=A 

//GO. SYSUDUMP DD SYSOUT=G 

X/SYSUDUMP DD SYSOUT=A 

//GO. SYSOUT DD SYSOUT=G 

X/SYSOUT DD SYSOUT=A yr\ 

XXSYSPUNCH DD SYSOUT=E ^~- \») 

//GO. MASTER DD SP ACE= ( TRK ,(500,100) , RLSE ) , 
// DCB=,.(OPTCD=E,LIMCT=5) ,UNIT=2314 

//GO. CARDS DD W 

// 

FOR FIG18 GO STEP1 

ALLOCATED TO PGM=*.DD 

ALLOCATED TO STEPLIB 

ALLOCATED TO DD1 

ALLOCATED TO SYSDBOUT 

ALLOCATED TO SYSUDUMP 

ALLOCATED TO SYSOUT 

ALLOCATED TO SYSPUNCH 

ALLOCATED TO MASTER 

ALLOCATED TO CARDS 



00800270 
00800280 
00800290 
00800300 

00800310 

00800320 
00800330 






.mv»± — o ; 



IEF236I ALLOC. 

IEF237I 230 

IEF237I 

IEF237I 

IEF237I 

IEF237I 

IEF237I 

IEF237I 

IEF237I 

IEF237I 



234 
250 
230 
250 
230 
250 
235 
230 



TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK-ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK-ID 
TRACK- ID 
TRACK-ID 
TRACK- ID 
TRACK-ID 
TRACK- ID 
TRACK- ID 
TRACK- ID 
TRACK-ID 
TRACK- ID 
TRACK-ID 
TRACK- ID 
TRACK-ID 



00149 
00149 
00149 
00149 
00070 
00149 
00149 
00149 
00149 
00149 
00149 
00149 
00149 
00149 
00149 
00149 
00149 
00039 
00149 
00149 
00149 
00149 
00157 
00149 
00149 
00149 
00149 
00149 
00149 



C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
C-REC 
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C-REC 
C-REC 
C-REC 
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C-REC 
C-REC 
C-REC 
C-REC 
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C-REC 
C-REC 
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Figure 30. Sample Program for a Randomly Created Direct File <Part 2 of 2) 
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Since this randomizing technique ® 
employs the prime number 69 1 as its 
divisor, the largest possible 
remainder is 690. By the interaction 
between the TRACK-LIMIT clause @ and 
the SPACE parameter Q) , the program 
formats 692 tracks (i.e., relative 
tracks 000-691). This establishes 
track 691 as the only track that can 
contain synonym overflow from track 
690. 

The DCB subparameter @ OPTC0=E is 
specified. If a synonym overflow 
condition arises, an extended search 
will be employed, and the additional 
record will be written in the first 
available position on the following 
track (s) . 



3. The DCB subparameter (f) LIMCT=5 is 
specified. This limits the extended 
search to five tracks. If no room is 
found within this limit, an invalid 
key condition results. A value should 
always be specified for the LIMCT 
subparameter when 0PTCD=E is 
indicated. Otherwise, the default 
value of LIMCT, which is zero, will 
result in an error that will be 
treated as an exceptional input/output 
condition. 

Note; The randomizing technigue chosen 
should minimize the number of synonym 
overflows for two reasons: 

1. The more extended search is employed 
during file creation, the more it will 
be required during record retrieval. 
Extended searches increase access time 
proportionately. 

2. When an extended search is employed, 
the adjusted value of the track 
identifier is not made available to 
the user after the execution of a 
fifSITE statement. The user, therefore, 
has no way of knowing the track on 
which an overflow record is actually 
written. 



File 
Organization 


Data Management 
Techniques 


Access 
Method 


KEY 
Clauses 


OPEN 

Statement 


Access 
Verbs 


CLOSE 
Statement 


D 


BSAM 


SEQUENTIAL 


ACTUAL 


INPUT 


READ [INTO] 
AT END 


[UNIT] 
[WITH LOCK] 


OUTPUT 


WRITE[FROM] 
INVALID KEY 


D 


BDAM 


RANDOM 


ACTUAL 


INPUT 


SEEK 

READ[INTO] 
INVALID KEY 


[WITH LOCK] 


OUTPUT 


SEEK 

WRITE [FROM] 
INVALID KEY 


I-O 


SEEK 
READ [INTO] 

INVALID KEY 
WRITE[FROM] 

INVALID KEY 


W 


BDAM 


RANDOM 


ACTUAL 


I-O 


SEEK 
READ[INTO] 

INVALID KEY 
WRITE[FROM] 

INVALID KEY 
REWRITE [FROM] 

INVALID KEY 


[WITH LOCK] 



Figure 31. Direct File Processing on Mass storage Devices 
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DD Statement Parameters Applicable to BSAM Input Files 



1 1 j 1 1 1 r 

DSNAMEJ Device JUNIT VOLUME JLABEL J SPACE J SUBALLOCf SPLITJ 



+ 



+ 



+ 



DISP 



h 

1/old\ 

j\SHRJ 
I 



DCB 



as | Mass Jnot requiredj[ SL or| 

1 Storage J if cataloged | SUL] J as 
J required! j | 

! I II 

I 1 i ! 

1 1 1 j 



na 



na 



,PASS 
|,KEEP 
,CATLG 
, DELETE 
,UNCATLG 



DD Statement Parameters Applicable to BSAM Output Files 



— , , , ( , j r j_ 

DSNAMEJ Device |UNIT VOLUME |LABEL J SPACE 1SUBALL0CJ SPLITJ 



H 

I Mass 
\ Storage 
J required 
1 
1 



+ 



+ 



DISP 



DCB 



J NEH 

I 

I 

I 

i l2te: 



as 



as 



J[SL or | as 
JSUL] | ELSE 
I I 
i ! 
! \ 
1 I 



(as 



na 



, KEEP 
l,CATLG 
,PASS 
,DELETE, 
MOD not 



1[DS0RG=DA] 
|OPTCD=[W,T] 



J meaningful 



DD Statement Parameters Applicable to BDAM Input and 1-0 Files 



j 1 1 1 1 1 r 

DSNAMEJDevice JUNIT VOLUME | LABEL | SPACE JSUBALLOCJ SPLITJ 



+ 



+ 



+ 



+ 



DISP 



1 



DCB 



-j 

i/OLD\ 

l\SHH/ 

1 

J 



as 



| Mass 



I not required} [SL or J 



JStorage j if cataloged JSUL] 
{required] 1 

II J 

I I 1 



na 



na 



i 

J na 



I 



',PASS 
LKEEP 

,CATLG 
(,UNCATLG| 

, DELETE 



J as specified 
J at file 
J creation 
I 



DD Statement Parameters Applicable to BDAM Output Files 



1 1 1 i 1 1 r 

DSNAMEJ Device JUNIT VOLUME J LABEL JSPACE JSUBALLOCJ SPLITJ 



-H 



—i 



DISP 



DCB 



+ 



4- 



+ 



+ 



+ 



+ 



-j 

J[DSOHG=DA] 
J OPTCD=[ W , E ] 
|LIMCT-n 



as J Mass J as II SL or I as J as 

JStorage | JSUB] JfiLSE J 

{required) J J ] 

II I 1 1 

II 111 

II 111 

L__ I 1 1 1 



Jna J NEH (,KEEP 



,CATLG 
,PASS 
\ (^DELETE 

| Note: MOD not 
) meaningful 

L ■ 



as = Applicable subparameters 
na = Not applicable 



Figure 32- JCL Applicable to Directly Organized Files 
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RELATIVE FILE PROCESSING 



Relative file processing is 
characterized by the use of the relative 
record addressing scheme. When this 
addressing scheme is used, the position of 
the logical records in a file is determined 
relative to the first record of the file 
starting with the initial value of zero. A 
NOMINAL KEY is used to identify randomly 
accessed records. Files with relative data 
organization must be assigned to mass 
storage devices. 



Format 



i NOMINAL KEY IS data-name 

r ~ 



1. The records (81, R2, . .., Rn) are 

formatted without a key area. 

2. The COUNT area contains a record ID: 

a. 2 bytes containing the cylinder 
number. 

b. 2 bytes containing the read/write 
head. 

c. 1 byte containing a record number 
from 1 through 255. 



Records on mass storage devices will 
always appear sequentially ranging from 
to n, where n equals the highest key 
contained in the file. 

The following example illustrates the 
relationship between the NOMINAL KEY and 
the positioning of records on a mass 
storage device. 



Data-name must be defined as an 
8- integer binary item whose value must not 
exceed 16,777,215. NOMINAL KEY must be 
defined in the Working-Storage section. 

The following example illustrates use of 
the NOMINAL KEY clause: 



ENVIRONMENT DIVISION. 



NOMINAL KEY IS THE- NOMINAL-KEY. 



DATA DIVISION. 



ENVIRONMENT DIVISION. 



NOMINAL KEY IS THE-NOMINAL-KEY. 



DATA DIVISION. 

FILE SECTION. 

FD RELATIVE-FILE 

LABEL RECORDS ARE STANDARD. 
01 REC-1 PIC X(80) 



WORKING-STORAGE SECTION. 



77 THE-NOMINAL-KEY PIC S9 (8) COMP SYNC. 



WORKING-STORAGE SECTION. 
! 77 THE-NOMINAL-KEY PIC S9(8) COMP SYNC. 



The relative file processing technique 
supports only unblocked fixed-length 
records. 

Figure 33 illustrates those parts of a 
relatively organized file that are of 
importance to a COBOL programmer. The 
track format is similar to the format 
described for directly organized files (see 
section "Direct File Processing"). The 
following is a list of significant 
differences: 



Consider REC-1 being written 200 times. 
With each execution of the WRITE statement, 
the content of THE-NOMINAL-KEY is 
incremented by 1, from through 199. 
Since a 2311 mass storage device has room 
for only thirty nine 80-character records 
on each track (see "Determination of File 
Space" in "Direct File Processing") REC-1 
will be written as follows: 

• Relative records through 38 will be 
on the first track. 

• Relative records 39 through 199 will be 
on the second through sixth tracks. 
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INDEX 
POINT 

t 

1 


GAP 
1 
1 


1 

V 


1 
1 

G 



RO 



J TRACK 1 | CAPACITY J 
| ADD BESS | G | RECORD J G 



R1 



I I i 

JCOUNTJDATAJ 
i 1 J 



R2 



i » 1 

1 I ! 

ICOUNTJDATAJ 
«. - l I 



Figure 33. Relatively Organized Data as it Appears on a Bass Storage Device 



Count Data 



Count Data 



Count Data 



i r 1 | 1 ] | ] 1 

G |01,00,1|REC-1j G j01,00,2iREC-1| G j 1, 00, 3 j SEC- 1 JG 

1st TRACK \ \ <0) | J 1 (1) J | J (2) J 

_ _ _ « j i i j i i i 



G |01,01, UBEC-1! G |01,01,2|REC-1J G J 1 , 1,3j SEC- 1 JG 
2nd TRACK | |{39) | J | (4 0) | J 1(41) J 

, t i J » I i i l i , 



Figure 34. Sample Format of Two Tracks of a Relative File 



Count 



Data 



r 1 "i 

G| 01,00,25|REC-1| 
\ I (38) | 

. i_ j j 



GJ01,01,25JREC-1| 
\ 1(77) J 



If the two tracks assigned to RELATIVE FILE 
are "cylinder 01 track 00" and "cylinder 01 
track 01," they would appear as shown in 
Figure 33. 



It is important to note t 
about the length of each rec 
capacity of each track and t 
record number, as indicated 
KEY is used by the system to 
exact location of each recor 
indicated in Figure 34, the 
each relative record number 
cylinder number, head number 
number, which are written in 
of each physical record. 



hat information 
ord, the 
he relative 
by the NOMINAL 

determine the 
d. As 

system converts 
into a unique 
, and record 

the count area 



Hate: Since count areas do not appear in 
1-0 buffers and there are no key areas, 
buffer size need be only large enough to 
accommodate data in HEC-1. 



Se quential Creatio n 



Relative files must be created 
sequentially using the file processing 
technique BSAM (Basic Sequential Access 
Method) . 



• The associated COBOL statements are 
summarized in Figure 36. 

* The associated JCL statements are 
summarized in Figure 37. 

Figure 35 illustrates the creation of a 
relative data set. 



Records in relative files, are arranged 
sequentially in the order in which they 
were written. The first record written is 
relative record 0, the second record is 
relative record 1, the nth record written 
is relative record n-1. A file containing 
1000 records will thus contain relative 
records through 999. The clause that 
allows the user to specify the relative 
record needed is the NOMINAL KEY clause. 

When a relative file is being created, 
the NOMINAL KEY clause may be specified. 

♦ If the NOMINAL KEY is specified and the 
value in the NOMINAL KEY (when a WRITE 
statement is executed) is greater than 
the next sequential relative number, 
the necessary number of dummy records 

1 is written by the compiler so that the 
actual record is written in the 
specified relative position. If the 
NOMINAL KEY for a WRITE statement is 
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less than the next sequential relative 
record number, the key is ignored and 
the record is written in the next 
available position. 



• If the NOMINAL KEY is 
the system begins writ 
record and increment 
record number by 1 for 
WRITE statement. When 
specified, the user is 
insertion of dummy rec 
time the compiler will 
records is during the 
CLOSE or CLOSE DNIT St 



not specified, 
ing at relative 
s the relative 
each additional 
the key is not 
responsible for 
ords. The only 

add dummy 
execution of a 
atement. 



Note ; Dummy records are identified by 
the presence of the figurative constant 
HIGH-VALOE in the first position of the 
record. 



The relative block number of the last 
record written is placed in the NOHINAL KEY 
after a WRITE, CLOSE, or CLOSE UNIT 
statement, if the key is specified. 

Once a file is created, more space 
cannot be allocated and the extent of the 
file cannot be increased. The only way to 
add records to an already existing file is 
to replace dummy records. Therefore, to 
allow for future additions, the user should 
create the file with as many excess dummy 
records as desired. 

The allocation of space to a relative 
file (both single-volume and multivolume) 
is similar to the allocation of space 
described for a sequentially created direct 
file. Highlights and essential differences 
are discussed below: 

• The relative file processing technique 
does not include a TRACK-LIMIT clause. 
Space allocation and formatting will, 
therefore, be determined by an 
interaction between the SPACE parameter 
of the DD card and the number of 
records written. 

• The total number of tracks formatted 
will be determined when the file is 
closed. Dummy records will be added to 
complete the current track, if 
necessary. 

• Tracks that are allocated but 
unformatted, and have been requested in 
track or block units, can be released 
by specifying the RLSE subparameter on 
the DD statement. 

• When a unit of a multivolume file is 
closed, all tracks that have been ' 
allocated on the current unit are 
formatted ( initialized with dummy 
records) before the next unit is made 



available. The RLSE subparameter of 
the DD statement applies only to the 
allocated tracks at the end of a data 
set. 

Note; In order to determine the amount of 
space a data set reguires, see Figures 
26-28. 



Sequen tial Reading 



The file processing technigue used to 
read a relative file sequentially is BSAM 
(Basic Sequential Access Method). 

• The associated COBOL statements are 
summarized in Figure 36. 

* The associated JCL parameters are 
summarized in Figure 37. 



when a relative file is being read 
seguentially, the records are made 
available in the sequence in which the 
records were written. Dummy records are 
also made available. The NOMINAL KEY, if 
specified, will be ignored. 



Random Acces s 



The file processing technique used to 
read or update a relative file randomly is 
BDAM (Basic Direct Access Method). 

• The associated COBOL statements are 
summarized in Figure 36. 

• The associated JCL statements are 
summarized in Figure 37. 



Since a relative file cannot be created 
randomly, the following restrictions exist: 

1. The file cannot be opened as an output 
file. 

2. The WRITE verb is not permitted. 



A relative file with BDAM can be opened 
as input or 1-0. Records are made 
available according to the contents of 
NOMINAL KEY. If the user wishes to update 
a file, it must be opened as I-o. Records 
can then be read into a single buffer, 
updated in that buffer, and rewritten from 
that buffer. If the user wishes to add 
records to a file, the file must have been 
created with excess dummy records. If 
dummy records are present, the file can be 
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opened as 1-0 and dummy records can be 
replaced by the additions. If dummy 
records are not present, additions cannot 
be made. 

Note: Records cannot be deleted, but can 
be replaced by dummy records. 

Figure 35 illustrates several basic 
characteristics of the relative file 
processing technique. It creates a 
relative file (B-FILE) using a card file 
(C-FILE) as input, C-FILE consists of 11 
cards in the following sequence: 



Card 








Number 




Card 


Contents 


1 


010 


NAME01 




2 


020 


NAME02 




3 


030 


NAME03 




4 


040 


NAHE04 




5 


050 


NAM EOS 




6 


060 


NAME06 




7 


000 


THIS CARD 


IS OUT OF SEQUENCE 


8 


070 


NAME07 




9 


080 


NAME08 




10 


090 


NAME09 




11 


100 


NAME10 





The program, during c 
the contents of NOMINAL 
execution of each WRITE 
creation, the relative f 
reopened as an input fil 
on the printer. The fol 
highlights some basic fe 
numbers in the program e 
corresponding numbers in 



reation, exhibits 
KEY after the 
statement. After 
ile is closed, 
e, and written out 
lowing discussion 
atures. Circled 
xample refer to 
the text. 



1. The nominal keys, (?) , that have been 
exhibited contain the relative record 
numbers of real records on the file. 
Relative records 10, 20, 30, 40, 50, 
60, 61, 70, 80, 90, and 100 are real; 
all others are dummy records formatted 



by a COBOL subrout 
nominal key N-KEY 
value taken from C 
000. This value, 
logical seguence s 
records 000 throug 
been written. The 
subroutine ignored 
adjusted it to the 
relative record nu 



ine. Note the 
=61. The initial 
-FILE, card 7, was 
however, was not in 
ince relative 
h 060 had already 
refore, a COBOL 
the value 000 and 
next appropriate 
ber (i.e. , 61) . 



2. The contents of N-KEY for the first 
WRITE, (2) , was 10. This means that 
a COBOL subroutine formatted relative 
records through 9, placing the 
constand HIGH-VALUE in the first 
position of each record. 

Note: The constant HIGH-VALUE is 
exhibited as a blank since FF is not a 
printable character. 

3. The contents of N-KEY for the second 
WRITE, © , was 20. Therefore, the 
COBOL subroutine formatted relative 
records 11 through 19. 

4. The contents of N-KEY for the seventh 
WRITE, ® , was initially 000. As 
explained in step 1 , N-KEY was 
adjusted to 61 and the record was 
written in the next available 
position. 

5. since this file was created on a 2314 
mass- storage device, the track 
capacity for R-FILE is 39 records per 
track. Relative record 100 is, 
therefore, on the third track. Since 
the file is closed after writing 
relative record 100, the COBOL 
subroutine formats the rest of the 
third track. In this case, it means 
the addition of 17 dummy records, (5), 
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C0001 
CC002 
C0003 
CC004 
0C005 
CC006 
CC007 
00008 
C0009 
COOIO 
C0011 
C0012 
C0013 
C001U 
C0015 
C0016 
C0017 
00018 
C0019 
C0020 
C0021 
C0022 
C0023 
C0024 
C0025 
C0026 
C0027 
C0028 
C0029 
C0030 
CC031 
C0032 
C0033 
C0034 
C0035 
C0036 
CC037 
C0038 
C0039 
C0040 
C0041 
C0042 
C0043 
C0044 
C0045 
00046 
C0047 
C0048 
CC049 
C0050 
C0051 



00101 

00102 

00103 

00104 

00105 

00106 

00107 

00108 

00109 

00110 

00111 

00112 

001125 

001126 

001127 

00113 

00114 

00115 

00116 

00117 

00118 

001184 

001185 

001186 

00201 

00202 

00203 

00204 

002041 

002042 

002043 

002044 

002045 

002046 

00205 

00206 

0*0207 

00208 

00209 

00210 

00211 

00212 

00213 

00214 

00215 

00216 

00217 

00218 

00219 

00220 

00230 



IDENTIFICATION DIVISION. 

PROGRAM-ID. CREATER. 

REMARKS. ILLUSTRATE CREATION OF A RELATIVE FILE. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE- COMPUTER. IEM-370. 

OBJECT-COMPUTER. IBM-370. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

SELECT R-FILE ASSIGN DA-2314-R-MASTER 
ACCESS IS SEQUENTIAL 
NOMINAL KEY IS N-KEY. 

SELECT C-FILE ASSIGN UR-S-CARDS. 

SELECT R-FILE2 ASSIGN DA-2314-R-MASTER. 

SELECT PRTFILE ASSIGN UR-S-PRTOUT. 
DATA DIVISION. 
FILE SECTION. 
FD R-FILE 

LABEL RECORDS ARE STANDARD 

RECORDING MODE IS F 

DATA RECORD IS DISK. 

DISK PIC X(80). 

R-FILE2 LABEL RECORDS ARE STANDARD. 

DISK2 PIC X(80). 

C-FILE 

LABEL RECORDS ARE OMITTED 

DATA RECORD IS CARD. 

CARD. 

02 C-KEY PIC 9(3). 

02 FILLER PIC X(77). 
FD PRTFILE LABEL RECORDS ARE OMITTED. 
01 PRT. 

02 FILLER PIC X. 

02 FIELD1 PIC X(132). 
WORKING-STORAGE SECTION. 
77 N-KEY PIC S9(8) COMP SYNC. 
PROCEDURE DIVISION. 

OPEN INPUT C-FILE 

OUTPUT R-FILE. 
Rl. READ C-FILE AT END GO TO EOJ1. 

MOVE C-KEY TO N-KEY. 

WRITE DISK FROM CARD. 

EXHIBIT NAMED N-KEY. GO TO Rl. 
EOJ1. 

CLOSE C-FILE R-FILE. 

OPEN INPUT R-FILE2 OUTPUT PRTFILE. 

READ R-FILE 2 AT END GO TO EOJ2. 

MOVE DISK2 TO FIELD1. 

WRITE PRT AFTER 1 LINES GO TO R2. 



01 
FD 
01 

FD 



01 



R2. 



EOJ2. 



CLOSE R-FILE2 PRTFILE. STOP RUN. 



Figure 35. Sample Program for Relative File Processing (Part 1 of 4) 
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F64-LEVEL LINKAGE EDITOR OPTIuNS SPECIFIED LIST, XREF, LET 
DEFmULT OPTION(S) US«D - SIZEM 196608, 65536) 



CROSS REFERENCE TABLE 



CCNTROL SECTION 



NAME 
CREATER 
ILBOCOMO* 


OitlGIN 

00 

BCO 


LENGTH 
BBA 
169 


ILeOOSP 


* 


030 


9F0 


ILBOEXT 


* 


1720 


50 


ILBOQIO 


* 


1770 


56E 


ILBOSAM 


* 


1CE0 


4C8 


IL80SPA 


* 


21A8 


670 


ILBOSRV 


* 


2818 


48E 


UBOBEG 


* 


2CA8 


128 


1LBUCMM 


* 


2000 


38B 


ILBOCVB 


* 


3160 


412 


ILBUMSG 


* 


3578 


F2 



ENTRY 
















NAME 


LOCATION 


NAME 


LOCATION 


NAME 


L3CATI0N 


NAME 


LOCATIDI 


I LBOCOM 


BCO 














ILBODSPO 


032 


ILBOOSSO 


032 










ILBOEXTO 


1722 


ILB0EXT1 


1726 










ILBOQIOO 


1772 














ILBOSAMO 


1CE2 














ILBOSPAO 


21AA 


IL60SPA1 


21AE 


ILB0SPA2 


2162 






ILBOSRVO 
ILBOSRVl 


2822 
2826 


ILB0SR5 
ILBOSTPl 


2822 
2826 


ILB0SR3 
ILBOST 


2822 
282A 


ILBOSR 
ILB3STP0 


2822 
282A 


ILBOBEGO 


2CAA 














ILBOCMMO 


20D2 


ILB0CMM1 


2D06 










ILBOCVBO 


3162 


ILB0CVB1 


3166 










ILBOMSGO 


357A 















LOCATION ReFERS TO SYMBOL aH CONTROL SECTION 



LOCATION REFERS TO SYMBOL IN CONTROL SECTION 



7B8 


ILBOSRVO 


ILBOSRV 


7C0 


ILBOEXTO 


ILBOEXT 


7C8 


ILBOSAMO 


ILBOSAM 


700 


ILBOSPAO 


1LB0SPA 


720 


ILBOCOMO 


I LBOCOMO 


*B68 


I LBOCOM 


ILBOCOMO 


*B70 


ILBOBEGO 


ILBOBEG 


4B78 


ILBOSN02 


•UNRESOLVEDIWl 


ENTRY ADORES* 


00 





7BC 

7C4 

7CC 

7D4 

27FC 

2B6C 

2B74 



ILB0SR5 

ILBOQIOO 

ILBODSPO 

ILBOSRVl 

ILBOCVBO 

ILBOCMMO 

ILBOMSGO 



ILBOSRV 
ILBOQIO 
ILBODSP 
ILBOSRV 
ILBOCVB 
ILBOCM* 
ILBOMSG 



TCTAL LENGTH 3670 
**4*G0 DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 
AUTHCRUATION CODE IS J. 



N-KEY 
N-KEY 
N-KEY 
N-KEY 
N-KEY 
N'KEY 
N-KEY 
N-KEY 
N-KEY 
N-KEY 
N-KEY 



00000010 
00000020 
00000030 
OOOOOOKO 
00000050 
00000060 
00000061 
00000070 
00000060 
00000090 
00000100 
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Figure 35* sample Program for Relative File Processing (Part 2 of U) 
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10 


NAMEOl \ 




10 


NAMEOl \ 




10 


NAMEOl 1 




10 


NAMEOl / 




10 


NAMEOl [ ^~n 
NAMEOl )(2) 




10 




10 


NAMEOl 1 




10 


NAMEOl \ 




10 


NAMEOl 1 




10 


NAMEOl 1 




010 


NAMEOl 




20 


NAME 02 \ 




20 


NAME02 ] 




20 


NAME 02 1 




20 


NAME02 f 




20 


NAME02 \/7\ 
NAME02 f\ZS 




20 




20 


NAME 02 I 




20 


NAWE02 I 




20 


NAME02 1 




C20 


NAME 02 J 




30 


NAME 03 




30 


NAME 03 




30 


NAME03 




30 


NAME 03 




30 


NAME 03 




30 


NAME 03 




30 


NAME 03 




30 


NAME 03 




30 


NAME03 




030 


NAME 03 




40 


NAME 04 




40 


NAME 04 




40 


NAME04 




40 


NAME04 




40 


NAME 04 




40 


NAM204 




40 


NAME 04 




40 


NAME04 




40 


NAME04 




C40 


NAME 04 




50 


NAME 05 




50 


NAME05 




50 


NAME 05 




50 


NAME 05 




50 


NAME 05 




50 


NAME05 




50 


NAME 05 




50 


NAME05 




50 


NAME05 




C50 


NAKE05 




60 


NAME 06 




60 


NAME 06 




60 


NAME06 




60 


NAME 06 




60 


NAME06 




60 


NAME 06 




60 


NAkE06 




60 


NAME 06 




60 


NAME 06 




060 


NAME 06 




CCO 


THIS CARD IS OUT 


OF SEQUENCE 



© 



Figure 35. Sample Program for Relative File Processing (Part 3 of 4) 
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70 


NAME07 


70 


NAME07 


70 


NAME 07 


70 


NAME07 


70 


NAME07 


70 


NAME07 


70 


NAME 07 


70 


NAME07 


070 


NAME07 


80 


NAME08 


80 


NAME08 


80 


NAME08 


80 


KAME08 


80 


NAME08 


80 


NAME08 


80 


NAME08 


80 


NAKE08 


80 


NAME08 


080 


NAME 08 


9C 


NAME 09 


90 


NAME09 


90 


NAME09 


90 


NAME09 


90 


NAME09 


90 


NAME09 


90 


NAKE09 


90 


NAME 09 


90 


NAME09 


090 


NAME 09 


CO 


NAME 10 


00 


NAME10 


CO 


NAME10 


00 


NAME10 


00 


NAME10 


00 


NAME10 


00 


NAME 10 


CO 


NAME10 


00 


NAME10 


100 
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Figure 35. Sample Prograa for Relative File Processing (Part 4 of tt) 
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Data Management 
Techniques 


Access 
Method 


KEY 
Clauses 


OPEN 
Statement 


Access 
Verbs 


CLOSE 
Statement 


BSAM 


SEQUENTIAL 


[NOMINAL] 


INPUT 


READ[INT0] 
AT END 


IUNIT] 
[WITH LOCK] 


NOMINAL 


OUTPUT 


WRITE [FROM] 
INVALID KEY 


BDAM 


RANDOM 


NOMINAL 


INPUT 


READ [INTO] 
INVALID KEY 


[WITH LOCK] 


1-0 


READ[INT0] 
INVALID KEY 

REWRITE [FROM] 
INVALID KEY 



INDEXED SEQUENTIAL FILE PROCESSING 



The indexed sequential file processing 
technique arranges records on the tracks of 
a mass -storage device in a sequence 
determined by keys. The key is a control 
field that is a physical part of the record 
(defined in the FD) and is specified by the 
RECORD KEY clause in the Environment 
Division. The RECORD KEY clause identifies 
for the compiler the location and length of 
that item within the data record that will 
contain the key. It must always be 
specified. 



Format 



1 

\ RECORD KEY IS data-name 

1 



D ata-name may be any fixed- length item 
from 1 through 255 bytes in length. 

When two or more record descriptions are 
associated with a file, a similar field 
must appear in each description, and must 
be in the same relative position from the 
beginning of the record, although the same 
data-name need not be used for both files. 

Data-name must be defined to exclude the 
first byte of the record in the following 
cases: 



1. Files with unblocked records. 

2. Files from which records are to be 
deleted. 

3. Files whose keys might start with a 
delete-code character (HIGH-VALUE). 



For further information, see 
OS/VS Data Management Services Guide. 



The position of each logical record in a 
file is determined by indexes created with 
the file and maintained by the system. The 
indexes are based on the RECORD KEYS and 
provide the following capabilities: 

• Write and later read or update logical 
records in a sequential, ascending 
order (using QISAfi) based on the 
collating sequence of the keys. This 
is done in a manner similar to that for 
sequential organization. 

• Read or update individual logical 
records in a random manner (using 
BISAM) . This method is somewhat slower 
per record than reading according to a 
collating sequence, since a search for 
pointers in indexes is required for the 
retrieval of each record. 

• Insert new logical records at any point 
within the file (using BISAM) . Using 
the indexes, the system locates the 
proper position for the new record and 
makes all necessary adjustments so that 
the sequence of the records, according 
to the keys, is maintained. 
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J. T T T T T T - 

DSNAME] Device J UNIT j VOLUME j LABEL j SPACE, SUEALLOC, SPLIT J 



DD Statement Parameters Applicable to ESAM Input Files 



DISP 



DCB 



as JMass ]not required | [SL or 
j Storage j if cataloged |SUL] 
| required J ] 



|OLD) ( .PASS 
ISHRJ ).KEEP 
. CATLG 
.DELETE 
.UNCATLG. 



na 



DD Statement Parameters Applicable to BSAM Output Files 



T T T T T T T T" 

DSNAME] Device j UNIT | VOLUME j LAEEL | SPACE | SUBALLOC ] SPLIT j 



DISF 



DCB 



as 



Mass 

Storage 

required 



as 



[SL orjas 
SUL] JRLSE 



as 



NEW [ .KEEP 
CATLG 

,PASS 
N . DELETE 

Note : MOD not 
meaningful 



CPTCD={W,T} 
[DSORG=DA] 



DD Statement PARAMETERS Applicable to EDAM Input and I-C Files 



T T T T T T T 

DSNAME] Device ] UNIT] VOLUME ] LABEL ] SPACE ,SUEALLOC„ SPLIT ] DISP | DCB 



as | Mass ]not required) [SL or 
j Storage ]if cataloged] SUL] 
] required | J 



roiDi 

ISHPj 



.. PASS 
.KEEP 
m CATLG 
.UNCATLG I 
.DELETE 



as has been 
specified 



as = Applicable subparameters 
na = Not applicable 



Figure 37. JCL Applicable to Relatively Organized Files 



Indexes 



There are two basic types of indexes: 
track indexes and cylinder indexes. There 
is one track index for each cylinder in the 
prine area (see "Indexed File Areas" for a 
description of prime area) . The track 
index is written on the first track of the 



cylinder that it indexes. Each entry in 
the track index contains the identification 
of a specific track in the cylinder and the 
highest key on that track (Figure 38) . 



Figure 38 is the representation of a 
track index with the following areas: 



RO 



Normal 



Overflew 



Normal 



Overflow 



|0100] ]CCCR] ]00010]0001] ]00010|0001] ]00025]0002| ]00025|0002| 

L J L J L J. J i X J I J. J L X J 



Home 
Address 



Key 



Data 



Key 



Data 



Key 



Data 



Key 



Data 



L . J 

Figure 38. Track Index 
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H ome Addres s — This field defines the 
physical location of the track in 
which the index appears. It 
indicates the cylinder in which the 
track is located and the read/write 
head that services the track. 



C OCB (Cylinder Overflow Control Record) 
— When a cylinder overflow area is 
specified (see "Indexed Sequential 
File areas" for a description of 
overflow areas) , RO of each track 
index is used to keep track of 
overflow records and space available 
in the cylinder overflow area. 



N ormal Entr y — There is one normal and 
one overflow entry for each usable 
track in the cylinder. The Normal 
Entry contains two areas: 



-i r- 



t r 



1 t 

1O05O0IQ000J |00945|0001J | 1550 | 0002 | .. . 

I I I I I J I I j 



Key Data Key Data Key Data 

' ' .\ / 

cylinder address 



Figure 39. Cylinder Index 



The cylinder index is formatted in the 
same fashion as the track index. Figure 39 
shows that the highest key on cylinder is 
500, the highest key on cylinder 01 is 945, 
the highest key in cylinder 02 is 1550, 
etc. 



• $£1 — the key of the highest 
record on the track specified in 
the Data area 



• Data — the home address of one of 
the prime tracks in the cylinder 

Figure 38 shows that the highest key 
on track 1 is 10 and the highest key 
on track 2 is 25. 

Overflow Entry — The overflow entry is 
originally the same as the normal 
entry. It is changed when an 
attempt is made to add a record to a 
prime track on which space is no 
longer available. In this case, the 
overflow entry keeps track of the 
logical sequence of records although 
physically the record may be added 
to an overflow area. 



Note: If an indexed sequential file is 
being read randomly, the system locates the 
given record by its key after a search of 
the cylinder index and the track index 
within the indicated cylinder. If the file 
is being read sequentially, starting, with 
the first record, no index search is 
performed. 



Records, in indexed sequential files, 
may be either blocked or unblocked; but 
must be F-mode records. Figures 40 and 41 
illustrate blocked and unblocked records as 
they appear on prime tracks of mass storage 
devices. 



BLOCKED RECORDS 



Count: contains control information 



There is one cylinder index for each 
file in which prime area data occupies more 
than one cylinder. The cylinder index 
contains one entry for each cylinder in the 
prime area; each entry pointing to the 
track index for a particular cylinder 
(Figure 39). 



Key.: contains the key of highest record in 
the block 



Data (1 T 2. ..., 6): each contains the 
information defined in the FD; including 
its oun record key. 



r t t t t 1 

| COUNT J KEY j DATA1 j DATA2 | DATA3 ] 
L X X X A- J 



r T T T T 1 

j COUNT ] KEY |EATA4 | DATA5 ] DATA6 | 
L X X . X X J 



1st Elcck 



2nd Elcck 



L . J 



Figure 40. Blocked Records on an Indexed File 
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r t t -\ 

j COUNT] KEY JDATAl] 
L X X J 



1st Elock 



ir t t 1 J 

j COUNT j KEY J DATA 2 | | 

I X -X J j 

2nd Elock 



i— 



Figure 41. Unblocked Records on an Indexed 
File 



UNBLOCKED RECORDS 
SfiJiJlt.: contains control information 



Key.: contains the key of the record that 
is in the block. 



j? a .ta. Jll.j.._12I g . ,.§*•£« .' each contains the 
information defined in the FD; including 
its own record key. 



Indexed S equential F ile Ar eas 



prime area on more than one cylinder. 
Space for this area will be allocated 
separately from the prime area if 
specifically requested. The index area 
must be contained within one volume, but 
that volume need not be the same device 
type as the prime area volume. If not 
specifically requested, the index area will 
automatically be constructed in the 
independent overflow area, or, if there is 
no independent overflow area, it is 
constructed in the prime area. 



Ov erflow,, Area: The overflow area is the 
area in which space is allocated for 
records forced from their original (prime) 
tracks by the insertion of new records. 
The fact that some records are stored in 
these areas, physically out of sequence, 
does not change the ability of QISAH to 
read the file in a logical sequence. An 
overflow area need not be specified if 
records are either not going to be added to 
the file, or sufficient space was 
originally reserved by writing dummy 
records in the prime area. 



The programmer specif 
of an indexed sequential 
be allocated for it in t 
the file when the file i 
instances, more than one 
required. (These DD sta 
described in "Using the 
Single Volume Files.") T 
allocated must be divide 
three areas, depending o 
programmer. These areas 
index area, and overflow 
overflow area is optiona 



ies the structure 

file and space to 
he DD statement for 
s created. In some 

DD statement is 
tements are 
DD Statements — 
he space being 
d into one, two, or 
n the needs of the 

are: prime area, 

area. The 
1. 



Prime Area: The prime a 
which data records are w 
file is created or reorg 
records are in a sequenc 
record keys. The track 
portion of the reserved 
reserve prime area space 
logical records may be i 
forcing records into an 
(described below) , dummy 
containing the figurativ 
HIGH-VALUE in the first 
may be written when the 
created. The prime area 
volumes and may consist 
noncontiguous areas. 



rea is the area in 
ritten when the 
anized. These 
e determined by the 
indexes also use a 
prime area. To 

so that new 
nserted without 
overflow area 

records (records 
e constant 
character position) 
file is being 

may span multiple 
of several 



Inde x Ar ea: The index area contains the 
cylinder indexes and, if requested, master 
indexes (described later) for the file. 
This area exists for any file that has a 



There are three ways in which space for 
an overflow area may be allocated: 



1. Cylinder overflow (Figure 42). Tracks 
on each cylinder can be reserved to 
hold the overflow of that cylinder 
(cylinder overflow option) . 



Independent Overflow (Figure 43) . 
Space may be requested for an 
independent overflow area, using the 
dsname (OVFLOW) DD statement, either 
on the same volume or on a separate 
volume of the same device type as that 
of the prime area. 



3. If the prime area is not filled when 
the file is created, the space 
remaining on the last cylinder on 
which data has been written will be 
designated as an independent overflow 
area (even though it is not requested 
directly) . If a separate independent 
overflow area is requested, the 
remainder of the prime area is 
available for resuming a load 
operation. 

Additional information about indexed 
file structure is contained in the 
publication OS/VS Data Hana qemeflt Seryjces 
Guide. 
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Figure 42. Cylinder Overflow Area 



An advantage of having a cylinder overflow 
area is that additional seek operations are 
not required to locate overflow records. A 
disadvantage is that there will be unused 
space if additions are unevenly distributed 
throughout the file. 



Creating .Indexed Se quenti al Files 



Indexed files must be created 
sequentially using QISAM (Queued Indexed 
Sequential Access Method) . Records must be 
arranged and written in ascending order 
according to the contents of RECORD KEY. 
If a WRITE statement is executed and the 
current contents of RECORD KEY is less than 
or equal to the previous contents of RECORD 
KEY, an INVALID KEY condition will result. 



The structure of an indexed sequential 
file, and the space to be allocated to it, 
is specified in a DD statement (s) . The 
space, which can be allocated in several 
different ways, must be sufficient for all 
areas of the file. 



DP STATEMENT REflUIREMEN 
FILES : The special par 
for DD statements that 
sequential files are di 
discussion is oriented 
sequential files on one 
the parameters used for 
multivolume files are n 
For more detailed infor 
parameters for both sin 
multivolume files, see 
p u bl ic a t io n s OS/VS_„„JCL._ 
JCL Services . 



TSFOR INDEXED 
amete.r requirements 
define new indexed 
scussed below. The 
to indexed 

volume. Many of 

creating 
ot discussed here, 
mation about 
gle- volume and 
either of the 
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Figure 43. Independent Overflow Area 



An advantage of having an independent 
overflow area is that less space need be 
reserved for overflows. A disadvantage is 
that accessing overflow records requires 
additional seek operations. 



A suggested approach is to have cylinder 
overflow areas large enough to contain the 
average number of overflows caused by 
additions and an independent overflow area 
to be used as the cylinder overflow areas 
are filled. 



ddname (name field) 

The name field of the first or only DD 
statement defining the indexed 
sequential file can contain the 
symbolic identification ddname or 
procstep. ddname. Succeeding DD 
statements for the file must not be 
named. 

DSNAME (DSN) 

This parameter must be specified and 
is coded as follows: 



DSNAME 
DSN 



dsname 



S&name 



[ (element) ] 



The first subparameter, dsname, or 
&&name must be the same in all the DD 
statements defining one data set. The 
element subparameter, INDEX, PRIME, or 
QVFLOw", indicates the type of area 
defined by the DD statement. If more 
than one DD statement is used to 
define a file, the order in which the 
statements should be placed in the 
input stream is as follows: 

DD DSNAME=dsname (INDEX) 
DD DSNAME=dsname (PRIME) 
DD DSNAME=dsname (GVFLOW) 
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Deviation from this sequence results 
in abnormal termination of the job. 
If the element subparameter is omitted 
PRIME is assumed. Note that an 
indexed sequential file cannot be 
specified by statements containinq 
only index and overflow elements. 



SPACE 



This parameter specifies the space to 
be allocated for each of the separate 
areas on the device and must be 
included. only cylinder (CYL) or 
absolute track (ABSTR) reguests are 
permitted, and with ABSTR the 
designated tracks must encompass an 
integral number of cylinders. All the 
DD statements defining one indexed 
seguential file must specify the same 
subparameter, either CYL or ABSTR. 
When all the DD statements specify 
CYL, all must also specify or omit 
CONTIG, depending on whether the space 
allocated is to be contiguous or 
noncontiguous. The directory or index 
quantity subparameter of the SPACE 
parameter is used to request the 
number of cylinders to be allocated 
for an index area embedded within the 
prime area {see "Space Parameter" in 
"Job Control Procedures") . An 
embedded index resides in the middle 
of a track and saves searching time by 
first determining which half of the 
track contains the requested record. 



SPLIT 



DISP 



DCB 



This parameter should never be 
specified for an indexed sequential 
file, either for sharing a cylinder 
with indexed seguential files or for 
sharing it with an indexed seguential 
file and another type of file. 



This parameter is written as it would 
be for any new file that cannot be 
cataloged. The CATLG subparameter 
must not be specified unless only one 
DD statement is used to allocate the 
file space (see "Cataloging Piles" for 
additional information about 
cataloging indexed sequential files). 



This parameter must be specified for 
each DD statement and is coded as 
follows; 

DCB=(DSORG=IS 

I , BUFNO=integer ] 

[ ,OPTCD={YfIJ Bj WJ LJ Mj U, NTM=in teger} ] 

[ ,BLKSIZE=integer ]) 

The DSORG=IS subparameter is required 
and indicates that the organization of 
the file is sequential. The DCB 
subparameters of all the DD statements 



defining one file must not conflict. 
For example, if the OPTCD=Y 
subparameter appears in the first DD 
statement, the subsequent DD 
statements should also contain 
OPTCD=Y. To ayoid any errors, code 
all the DCB subparameters on the first 
DD statement. Code DCB=*.ddname on 
the remaining statements; ddname is 
the name of the DD statement that 
contains the DCB subparameters. The 
subparameters are discussed below. 



BO"FNQ=number of 
This subparaa 
the number of 
to the file i 
clause is spe 
the source pr 
number is 255 
number allowe 
differ and is 
generation ti 



buffers 
eter is used to specify 

buffers to be assigned 
f no RESERVE or SAME AREA 
cified for the file in 
ogram. The maximum 
; however, the maximum 
d for an installation may 

established at system 
me. 



OPTCD=options 

This subparameter is used to tell the 
system that certain additional 
facilities are to be provided for this 
file. Any combination of the 
following options can be specified for 
the OPTCD subparameter. If more than 
one option is specified, the options 
are written as a character string 
(i.e., without intervening commas or 
blanks) . Note that if certain of 
these options are used, an additional 
subparameter must also be specified as 
indicated. In addition to the 
information supplied, the COBOL 
compiler will supply OPTCD=L. 

• OPTCD=L: This option requests 
that the control program delete 
marked records. Marked records 
will be deleted when space for 
new records is reguired. 

• OPTCD=Y: This option requests 
that a cylinder overflow area be 
created. It specifies that a 
certain number of tracks on each 
cylinder are to be reserved to 
contain any overflow records 
from other tracks on that 
cylinder. Another DCB 
subparameter, CYLOFL=xx, must 
also be written. The xx 
specifies the number of tracks 
on the cylinder to be reserved 
for the overflow area. The 
maximum number is 99. 

• OPTCD=I : This option requests 
that an independent overflow 
area be reserved. It is used in 
conjunction with DSNAME=dsname 
(OVFLOW) parameter in the DD 
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statement used to allocate the 
independent area. 



OPTCD=M: Thi 
that a master 
(see "Master 
discussion of 
Another DCB s 
NTM=xx, must 
It specifies 
of tracks to 
cylinder inde 
level index i 
maximum value 
specified is 



s option requests 
index be created 
Index" for a 

master indexes) . 
ub para meter, 
also be written, 
the maximum number 
be contained in the 
x before a higher 
s created. The 

that can be 
99. 



OPTCD=R: This option requests 
reorganization criteria 
feedback, as described in 
"Reorganizing Files." 

OPTCD=W: This option requests 
the system to perform a write- 
validity check. 

OPTCD=U: This option requests 
that track index entries be 
accumulated in main storage 
until there are enough entries 
to fill a track. When the track 
is full all the entries will be 
written out. If enough main 
storage cannot be obtained 
entries will be written two at a 
time. 



Hsiflg-tfe£_PP_S,tatements -- .Single- Volume 
£iiss: The following examples refer to 
files that can be contained on one volume. 
Additional information about DD statements, 
including details on multivolume file 
allocation, can be found in the publication 
OS/ VS JCL Reference. 



All three areas for an indexed 
sequential file can be contained on a 
single volume if they are small enough. If 
such is the case and the programmer elects 
to allow the system to subdivide storage 
into the prime and index areas when the 
file is created, he need only code the 
following DD statement: 



//ddname DD DSNAME=dsname (PRIME) , X 

// SPACE= (CYL, (no. of X 

// cylinders)) ,UNJT=unit, X 
// DCB=(DSORG=IS,...) 



The DD statement given will produce a prime 
area with the index area occupying the last 
cylinder (s) of the space in the prime area. 
If any track (s) remain on the last cylinder 
after the index area, they are used as an 
independent overflow area; if no track (s) 
remain, an overflow area does not exist. 

If the programmer definitely wants an 
independent overflow area, he must provide 
a second DD statement as follows: 



The following is an example of how 
the OPTCD subparameter can be used: 

DCB= (DS0RG=IS,0PTCD=H,NTM=2Q) 



The foregoing example requests that a 
master index be created when the 
cylinder index exceeds 20 tracks. 



BLKSIZE=integer 

specifies the blocksize. This clause 
is used only if BLOCK CONTAINS 
RECORDS was specified at compile time. 

H2£§* Figure 44 shows the parameters that 
may be used in a DD statement when 
processing indexed sequential files opened 
as output. Additional information about 
indexed sequential file structure is 
contained in the publication O S/VS Data 
Mana gem ent Services Guide . 



//ddname 

// 

// 

// 

// 

// 

// 

// 

// 

// 



DD 



DD 



DSNAME=dsname(PRIHE) , 
SPACE= (CYL, (no. of 
cylinders) ) ,UNTT=unit, 
VOLUME=SER=2 22222, 
DCB= (DSOR G=I S , OPTCD=I , . 
DSNAME=dsname (OVFLOW) , 
SPACE= {CYL, (no. of 
cylinders)) , UNIT=unit, 
VOL0ME=SER=222222, 
DC B=*. ddname 



• -) 



These DD statements will produce a prime 
area and a separate overflow area with the 
index area at the end of the overflow area. 
All three areas reside on the same volume. 



Note: When more than on DD statement is 
used, only the first can be named. The 
others must not have a data definition name 
(ddname) but all must have the same data 
set name (dsname) . 
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i ddname 
i 



I 

IDSNAHE 
| (DSN) 



j Device 
j. 



JOMIT 
| 



| SEP, AFF 

J 

j 



J VOLUME 



J LABEL 



SPACE 



jSUBALLOC 

j 



1 SPLIT 
| 



f DISP 
J 



j. 

1DCB- 



ddname used only for first DD 
statement of each file 



(dsnamel 
(S&name/ 



(INDEX) 
(PRIME) 
(OVFLOH) 
Note: If more than one DD 
statement is used, elements 
must be in this order. 



Mass storage reguired 



DEFER not permitted 



Restricted, see "Job Control 
Procedures" 



Volume sequence number subparam- 
eter not applicable 



S.L 



CYL ,. 

ABSTR 



[,,CONTIG] 



-i 



Not applicable 



Not applicable 



NE»* 



,KEEP " 

,PASS 

.DELETE 



Required: DSORG=IS 
Optional: B0FNO=xxx BLKSlZE=xxxx 
OPTCD= {«JHiY|I|R|L|0} 



I 1 MOD not meaningful. CATLG allowed only 
J if all areas are allocated with a single 
J DD statement 

j 2 The DCB parameter should be the same for 
j each DD statement 

Figure 44. DD Statement Parameters 

Applicable to Indexed Files 
opened as Output 



//ddname 


DD 


// 


DD 


// 


DD 



These DD statements will produce two 
separate areas: index and prime. Each 
area is on the same volume. 

If, along with more control of his 
index, the programmer wishes an independent 
overflow area, a third DD statement 
(OVFLOB) can be specified, as detailed 
earlier. The sequence will be: 



DSNAME=dsname (INDEX) ,... 
DSNAME=dsname (PRIHE) , . . . 
DSNAME=dsname (OVFLOW) ,.. 



These DD statements will produce three 
separate areas: index, prime, and 
overflow. 

Note that the OPTCD subparameter of the 
DCB parameter in each of the DD statements 
must specify an independent overflow area 
(OPTCf)=I). All three areas reside on the 
same volume if so specified in the VOLUME 
parameter. 



Note: The sequence of the DSNAME parameter 
elements in all of the foregoing examples 
must be followed when placing the DD 
statements into the input stream, or an 
abnormal termination of the job will 
result. 

The example in Figure 45 defines a new 
indexed sequential file that consists of 
three separate areas. All three areas 
reside on the same volume. The volume is 
on an IBM 2314 Disk Storage Drive. 



Ca taloging Files : 
cataloged if: 



An indexed file can be 



All the areas of the file are allocated 
with a single DD statement. Such a 
file is cataloged in the usual manner 
by specifying the DISP parameter in the 
DD statement: 



If the programmer desires more control 
in the placement of the index area, he can 
subdivide storage before the data set is 
created by providing another DD statement 
as follows: 

//ddname DD DSNAME=dsname (INDEX) , 



// 
// 
// 
// 
// 
// 
// 
// 
// 



X 

SPACE=(CYL,(no. Of X 

cylinders) ) ,UNIT=unit, X 

VOLUME=SER=333333, X 
DCB=(DSORG=IS,...) 

DD DSNAME=dsname(PRIME) , X 

SPACE=(CYL, (no. of X 

cylinders) ).UNIT=unit, X 

VOLUME=SEB=333333, X 
DISP= (disp) , DCB=*. ddname 



DISP=(NEW,CATLG) 

The areas are allocated with more than 
one DD statement, but all volumes are 
on the same type of device. Such a 
file is cataloged using the IEHPROGM 
utility program (see the publication 
OS /VS Dtilitie s) . 



An indexed sequential file that is being 
created cannot be cataloged if its areas 
are on different device types. An existing 
indexed sequential file cannot be cataloged 
through the specification of the CATLG 
subparameter of the DISP parameter in the 
DD statement. 
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DSNAHE=ISM (INDEX) , 0NIT=231 4,SPACE= (CYL, (1) ) , 
V0LUME=SER=1 1 1111, DCB= (DSORG=IS,OPTCD= I, . . . ) 
DSNAME=ISB (PRIME) , UNIT=231 4,SPACE= (CYL, (5) ) r 
V0LUME=SER=1 1 1 1 1 1, DISP= (,KEEP) , DCB=*. FILE 
DSNAME=ISM (OVFLOW) ,UNIT=23 14,SPftCE= {CYL, (1) ) 
VOLUME=SER=1 11 111,DISP= (,KEEP) ,DCB=*.FILE 



Example of DD Statements for New Indexed Files 



Note: The DD statement (s) defining a new 
or existing indexed sequential file can 
appear in cataloged procedures. 



Calc ulating Space Requirements; To 



determine the number of 
for an indexed sequentia 
programmer must consider 
records that will fit on 
number of records that w 
and the amount of space 
indexes and overflow are 
computations, additional 
required for device over 



cylinders reguired 

1 file, the 
the number of 
a cylinder, the 

ill be processed, 

required for 

as. In making the 
space is also 

head. 



Note; The allocation of space to the 
different areas of an indexed sequential 
file is permanent. New allocations can be 
achieved only by recreating the file, it 
is, therefore, important to remember: 

• Unused space on the last cylinder on 
which data was written, in the prime 
area, is converted to an independent 
overflow area. Space allocated in 
excess of this cannot be released and 
will be wasted. 

• Excess space allocated to overflow or 
index areas cannot be released. 

Detailed information on space allocation 
can be found in the publication OS/Y S D ata 
Management services Guide. 



Master Index: QISAM providas a master 
index facility to avoid inefficient serial 
searches of large cylinder indexes. The 
master index provides an index to the 
cylinder index. The programmer can specify 
with the DCB parameter in his DD 
statement (s) (see "DD Statement 
Requirements for Indexed sequential Files" 
in "Creating Indexed Sequential Files") 
that a master index be built if the size of 
a cylinder index exceeds a certain number 
of tracks. Each entry in the master index 
points to a track of the cylinder index. 
If the size of the master index exceeds the 
number of tracks specified in the NTM 
parameter of the DD statement, the master 
index is automatically indexed by a higher 
level master index. Three such higher 
level master indexes can be constructed. 



COBOL, T Cons iterations: when creating 
indexed sequential files, the QISAM file 
processing technique is used. The 
following COBOL programming considerations 
should be noted: 

• RECORD KEY Clause. The RECORD KEY 
clause in the SELECT sentence of the 
Environment Division is required. It 
is used to specify the location of the 
key within the record itself. If the 
RECOBD KEY clause has a PICTURE clause 
that specifies that the item is binary 
(COMPUTATIONAL) , zero is the lowest 
number acceptable as the first record. 
A negative key is considered to be 
larger than a positive key; therefore, 
if a record is inserted into the file, 
a negative key would place the record 
after those records with positive keys. 

• Dummy Records. To reserve space for 
records to be added at a later time, 
when creating indexed sequential files, 
dummy records can be written with the 
delete code (the figurative constant 
HIGH-VALUE) in the first byte. Dummy 
records and their deletion are 
described in "Using the WRITE 
Statement. " 

• Required and optional COEOL statements 
are summarized in Figure 47. 



RgaMag-Qg u pdati ng Indexed Sequential 
Fi les S equenti ally 



QISAM can be used to read or update an 
existing indexed sequential file. Adding a 
record to an already existing file, 
however, can be done only with BIS AM {see 
"Accessing an Indexed File Randomly") . 

When QISAM is used to read an input 
file, the READ statement makes available 
one logical record at a time in an 
ascending sequence determined by the record 
keys. Dummy records are not made 
available. If there are records in the 
overflow area, this sequence will not 
correspond exactly to the physical sequence 
of the records in the file. The file must 
have been created using QISAM. 



User Non-VSAM File Processing 127 



When QISAM is used to update an 1-0 
file, the READ and REWRITE statements 
permit updating-in-place or deletion of a 
logical record. Logical records are read 
sequentially and may be either updated and 
rewritten, or rewritten unaltered, from the 
same area. Alteration of record length or 
insertion of new records is not permitted. 
A logical record is marked for deletion by 
moving the figurative constant HIGH-VALUE 
into the first character position of the 
record and then using the REWRITE 
statement. Records in the file that 
contain this deletion code are not made 
available on input. 

The discussion that follows is primarily 
concerned with indexed sequential files 
that can be contained on a single volume, 
additional information about processing 
existing indexed sequential files accessed 
sequentially, including multivolume files, 
can be found in the publication OS/ V S JC L 
Reference. 

Para mete r Requirements: In the DD 
statement <s) indicating an existing indexed 
file, the following differences and 
reguirements should be noted: 



DCB 



The DSORG=IS subparameter must be 
specified, whereas the BOFNO 
subparameter is optional. The OPTCD 
field must not be specified again. 
Any OPTCD subparameter facilities that 
were specified when the file was 
created are in effect as long as the 
data set exists. For example, if the 
programmer specified the 
write-validity check option (OPTCD=W) 
when he created the file, the option 
is still in effect at the time of any 
subsequent WRITE statement. The 
BLKSIZE and LRECL subparameters must 
not be specified. 



DSNAME (DSN) 

This parameter is written 
DSNAME=dsname. The element 
subparameters (INDEX, PRIME, OVFLOW) , 
must not be written. 

DISP 

The first subparameter must be OLD. 
The second subparameter cannot be 
CATLG or UNCATLG (see "Cataloging 
Files" above for more information on 
cataloging indexed seguential files). 

Note: For further information about 
Indexed Sequential parameters, see "DD 
Statement Requirements for Indexed 



Sequential Files" in "Creating Indexed 
Sequential Files." 

Only one DD statement is needed to 
specify an existing file if all of the 
areas are on one volume. The following is 
an example of a DD statement that can be 
used when processing a single- volume QISAM 
file. 



//ddname DD DSNAME=dsname, 

// DCB= <DSORG=IS,...) , 

// 0NIT=unit,DISP=OLD 



Further details about DD statements for 
existing single-volume and multivolume 
indexed sequential files can be found in 
the publication OS/VS ^ CL R ef erence. 
Re fere nce. 

N ote : Figure 46 shows the parameters that 
may be used in a DD statement when 
processing indexed sequential files opened 
as INPUT or 1-0. Additional information 
about indexed file structure is contained 
in the publication QS/VS. p ata Management 
Servi ces Guide . 

Reorganizi ng Files : As new records are 
added to an indexed sequential file, chains 
of records may be created in the overflow 
area if one exists. The access time for 
retrieving records in an overflow area is 
greater than that required for retrieving 
records in the prime area. Input/output 
performance is, therefore, sharply reduced 
when many overflow records develop. For 
this reason, an indexed sequential file can 
be reorganized as soon as the need becomes 
evident. The system maintains a set of 
statistics to assist the programmer when 
reorganization is desired. These 
statistics are maintained as fields of the 
file's data control block. They are made 
available when APPLY REORG-CRITERIA is 
specified. If these statistics are 
desired, the OPTCD subparameter of the DCB 
parameter must have included the OPTCD=R 
parameter in each of the DD statements when 
the file was created. Additional 
information about reorganizing files is 
contained in the publication 0S/7S Data 
Management Services Guide. 

Se quentia l Retrieval Using the START 
Statement: For indexed sequential INPUT 
and 1-0 files, retrieval starts with the 
first nondummy record in the file. If the 
programmer wishes to begin processing at a 
point other than the beginning of the file, 
he can do so through the use of the START 
verb. When the START statement is used, 
the retrieval starts sequentially from the 
record specified in the NOMINAL KEY. 
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ddname used only for first DD 
statement of each file 



dsname 

Note: Element subparameter must 
not be used. 



Mass storage required 



Applicable subparameter 

NoJt£ : Not needed if file is 
cataloged. 



Restricted; see "Job Control 
Procedures" 



Applicable subparameters 



SL 



Not applicable 



Not applicable 



Not applicable 



OLD* 



,KEEP 
,PASS 
, DELETE. 



Required: DSORG=IS 

Optional: BUFNO=xxx (not allowed 
for BISAM) 
LRECL=xxx 



i»CATLG UNCATLG not permitted. 

i 

Figure 46. DD Statement Parameters 

Applicable Indexed Sequential 
Files Opened as INPUT or 1-0 



constant HIGH-VALUE into the first 
character position of the record (unless it 
has been changed by the program collating 
sequence — in which case a x'FF' must be 
moved) . The record is not physically 
deleted unless it is forced off its prime 
track, by the insertion of a new record (see 
"Using the WRITE Statement" in "Accessing 
an Indexed File Randomly") , or if the file 
is reorganised. Records marked for 
deletion may be replaced (using BISAM) by 
new records containing equivalent keys. 
Execution of the READ statement in QISAM 
does not make available a record marked for 
deletion, whether the record has been 
physically deleted or not. Dummy records 
and deletion are discussed further in 
"Accessing an Indexed Sequential File 
Randomly." 



Recessi ng an Indexed Sequential File 
landomly. 



The file processing technique used for 
random retrieval of a logical record, the 
random updating of a logical record, and/or 
the random insertion of a record is BISAM 
(Basic Indexed Sequential Access Method) . 
Hhen accessing an indexed sequential file 
randomly, both NOMINAL KEY and RECORD KEY 
must be specified. The format of the 
NOMINAL KEY is described briefly below: 



Format 



NOMINAL KEY IS data-name 



CO BOL Co nsiderat io ns: When processing an 
already existing file with QISAM, the 
following COBOL programming considerations 
should be noted: 

• RECORD KEY Clause. The RECORD KEY 
always in the SELECT sentence of the 
Environment Division is required, just 
as it is when creating the file. Note 
other record key considerations under 
"Accessing an Indexed Sequential File 
Randomly." 

• Delete Option. In order to keep the 
number of records in the overflow area 
to a minimum, and to eliminate 
unnecessary records, an existing record 
may be marked for deletion. This is 
done by moving the fiqurative 



Data-name may be any fixed-length 
Working storage item from 1 through 255 
bytes in length. If it is part of a 
logical record, it must be at a fixed 
displacement from the beginning of that 
record description (see the publication IBM 
VS COBOL f or OS/VS for additional 
information) . 



Since a RECORD KEY is used to identify a 
record to the system, the record keys 
associated with the logical records of the 
file may be thought of as a table of 
arguments. Hhen a record is read or 
written, the contents of NOMINAL KEY is 
used as a search argument that is compared 
to the record keys of the file. 
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The following example illustrates the 
use of the NOMINAL KEY clause. 



ENVIRONMENT DIVISION. 



NOMINAL KEY IS NOM-KEY 
RECOED KEY IS REC-KEY. 



Notes.: 

• Records with a key higher (or lower) 
than the current highest (or lowest) 
key of the file may be added. 

• Whenever a WRITE statement is executed 
the contents of RECORD KEY and NOMINAL 
KEY oust be identical. Except in the 
case of dummy records, this value must 
be unique in the file. 



DATA DIVISION. 

FILE SECTION. 

FD INDEXED-FILE 

LABEL RECORDS ARE STANDARD. 
01 REC-1. 

02 DELETE-CODE PIC X. 

02 REC-KEY PIC 9(5). 



Using the REWRITE Statement: If a record 
is to be updated, the indexed file should 
be opened as 1-0 and the REWRITE statement 
should be used. All REWRITE statements 
must be preceded by a READ statement. 
However, a READ statement can be followed 
by either a WRITE, REWRITE, or another 
READ. 



WORKING-STORAGE SECTION. 

77 NOM-KEY PIC 9 (5) . 



Note: Whenever a REWRITE statement is 
executed the value contained in NOMINAL KEY 

and RECORD KEY must be identical. 



Because of their complementary use of 
the indexed file organization, much of the 
information discussed above for QISAM also 
applies to BIS AM. Differences are noted 
below. 
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In the first method, the key to be added 
is a new key value. The record is inserted 
in place so that the sequence of the keys 
is maintained. If an overflow area exists, 
the insertion may cause records to be 
forced off the prime track into the 
overflow area. Dummy records forced off 
the track in this way are physically 
deleted and are not written in the overflow 
area. 



In the second method, the 
record to be added has the s 
that of a known dummy record 
record has not been physical 
is replaced by the new recor 
been physically deleted, the 
inserted as though it had a 
If the key of the record to 
the same value as a record o 
dummy record, an INVALID KEY 
result. 



key of the 
ame value as 

If the dummy 
ly deleted, it 
d. If it has 

record is 
new key value, 
be added has 
ther then a 

condition will 



Using the R E AD ,,. Statement: Records are 
retrieved on the basis of the value 
specified in the NOMINAL KEY. If the key 
of a record marked for deletion is 
specified and the record has not been 
physically deleted, it will be produced. 
If the record has been physically deleted, 
the READ statement will cause an INVALID 
KEY condition and control will go to the 
INVALID KEY routine if specified. 



fiote: Although the RECORD KEY clause must 
be specified, no value need be moved to the 
record key field before the execution of 
the READ statement. The search for the 
desired record is based on the contents of 
NOMINAL KEY. 



COBOL Considerations: When processing an 
indexed file randomly, the following COBOL 
programming considerations should be noted; 

* RECORD KEY Clause and NOMINAL KEY 

Clause. The RECORD KEY and NOMINAL KEY 
clauses in the SELECT sentence of the 
Environment Division are required. The 
RECORD KEY clause is used to specify 
the location of the key within the 
record itself. The NOMINAL KEY is used 
as a search argument to locate the 
proper record, and must not be defined 
within the file being processed. Note 
that since a RECORD KEY Is defined 
within a record, the contents of RECORD 
KEY are not available after a WRITE 
statement has been executed for that 
record. 
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Figure 47. Indexed Sequential File Processing on Hass Storage Devices 



TRACK-AREA Clause. Specifying the 
clause results in a considerable 
improvement in efficiency when a record 
is added to the file. If a record is 
added and the TRACK-AREA clause was not 
specified for the file, the contents of 
the NOMINAL KEY field are unpredictable 
after the WRITE statement is executed. 
In this case, the key must be 
reinitialized before the next WRITE 
statement is executed. 



Even if TRACK-AREA is specified, if the 
addition of a record causes another 
record to be bumped off the track and 
into the overflow area, the contents of 
the NOMINAL KEY are unpredictable after 
a WRITE. 
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The following sections summarize the DD 
statement parameters and show examples for 
various uses of the DD statement. These 
sections include information about 
cataloging data sets and creating or 
referring to generation data groups; 
examples of cataloged data sets and 
partitioned data sets are included. For 
additional information about partitioned 
data sets see "Libraries." Also see 
"Appendix I: Checklist for Job Control 
Procedures" for additional examples of the 
DD statement used in job control 
procedures. 



• APPLY CORE-INDEX Clause. This clause 
specifies that the highest level index 
will reside in core storage during 
input/output operations. Otherwise, 
the index will be searched on the 
volume, and processing time will be 
longer. 

* Required and optional COBOL statements 
are summarized in Figure 47. 



CREATING A NON-YSAM DATA SET 



When creating a non-VSAM data set, the 
programmer ordinarily will be concerned 
with the following parameters: 

1. The data set name (DSNAKE) parameter, 
which assigns a name to the data set 
being created, 
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The unit (ONTT) parameter, which 
allows the programmer to state the 
type and quantity of input/output 
devices to be allocated for the data 
set. 

The volume (VOLUME) parameter, which 
allows specification of the volume in 
which the data set is to reside. This 
parameter also gives instructions to 
the system about volume mounting. 

The space (SPACE) , split cylinder 
{SPLIT) , and suballocation (SUBALLOC) 
parameters, for mass storage devices 
only, which permit the specification 
of the type and amount of space 
required to accommodate the data set. 

The label (LABEL) parameter, which 
specifies the type and some of the 
contents of the label associated with 
the data set. 



6. 



7. 



The disposition (DISP) parameter, 
which indicates what is to be done 
with the data set by the system when 
the job step is completed. 



The DCB parameter, 
programmer to spec 
information to com 
associated with th 
"User-Def ined File 
additional informa 
at execution time 
constructed by the 
set defined in the 



which allows the 
ify additional 
plete the DCB 
e data set (see 
s") . This allows 
tion to be specified 
to complete the DCB 
compiler for a data 
source program. 



Figure 48 shows the subparameters that 
are frequently used in creating data sets. 
Additional subparameters are discussed in 
"Job Control Procedures." 
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Figure U8. DD Statement Parameters Frequently Used in Creating Data Set: 
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Data sets whose destination is a printer 
or card punch are created with the DD 
statement parameters UNIT and DCB. 



UNIT: Required. code unit information 
using the 3-digit address (e.g., UNTT=00E) , 
the type (e.g., UNIT=1U0 3), or the 
system-generated group name (e.g., 
UNIT=PRINTER) . 



DISP: Required for data sets that are to 
be cataloged, passed, or kept. The 
programmer can specify conditional 
disposition as the third term in the DISP 
parameter to indicate how the data set is 
to be treated if the job step abnormally 
terminates. 



Creating Sequential (BSAM or QSAM) Data 

Sets on Mass St orage Devices 



DCB: Required only if the data control 
block is not completed in the processing 
program. Valid DCB subparameters are 
listed in "Appendix C: Fields of the Data 
Control Block." 



Sequential data sets are created using 
combinations of the DD statements 
parameters UNIT, DSNAME, VOLUME, LABEL, 
DISP, DCB, and one of the space allocation 
parameters SPACE, SPLIT, or SUBALLOC. 



Creating Dat a Sets o n Magnetic Tape 



Tape data sets are created using 
combinations of the QD statement parameters 
UNIT, LABEL, DSNAME, DCB, VOLUME, and DISP. 



UNIT: Required, except when volumes are 
requested using VOLUME=REF. A unit can be 
assigned by specifying its address, type, 
or group name, or by requesting unit 
affinity with an earlier data set. 
Multiple output units and defer volume 
mounting can also be requested with this 
parameter. 

LABEL: Required when the tape has user 
labels or does not have standard labels, 
and when the data set does not reside first 
on the reel. It is also used to assign a 
retention period and password protection. 

DSNA ME : Required for data sets that are to 
be cataloged or used by a later job. 
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VOLUME: Optional, this parameter is used 
to request specific volumes. If VOLUME=REF 
is specified, and the existing data sets on 
the specified volume (s) are to be saved, 
indicate the data set sequence number in 
the LABEL parameter. 



UNIT: Required, except when volumes are 
requested using VOLUME-REF or space is 
allocated usinq SPLIT or SUBALLOC. Assign 
a unit by specifying its address, type, or 
group name, or by requesting unit affinity, 



DSNAME: Required for all but temporary 
data sets. 

iS^Sli Required to specify label type and 
to assign a retention period or password 
protection. 
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VOLUME: optional. This parameter requests 
specific volumes (SEE and REF) , specific 
volumes when the data set resides on more 
than one volume (seq #) , multiple 
nonspecific volumes (volcount) , private 
volumes (PRIVATE) , or private volumes that 
are to remain mounted until the end of the 
job (RETAIN) . 

DISP : Required for data sets that are to 
be cataloged, passed, or kept. The 
programmer can specify conditional 
disposition as the third term in the DISP 
parameter to indicate how the data set is 
to be treated if the job step abnormally 
terminates. 

ggACE, ...SPLIf , .SUBALLOC: One of these is 
required for all new mass storage data 
sets. 
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Creating, Direct IJBDAjl] Pat assets. 



Direct (BDAM) data sets are created 
using the same subset of DC statement 
parameters as sequential data sets, with 
the exception of the SPLIT parameter- 
Valid DCB subparameters for BDAM data sets 
are listed in "Appendix C: Fields of the 
Data Control Block." 
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Creating Indexed (BISAM and OISAM) Data 
Sets 



i>YSOUT: Required. The output class 
through which the data set is routed must 
be specified. Output classes are 
identified by a single alphanumeric 
character. 
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New data sets can be written on a system 
output device in much the same way as 
messages. A data set is directed to the 
output stream with the SYSOUT and DCB 
parameters. 

SYSOUT: Required. The output class 
through which the data set is routed must 
be specified. Output classes are 
identified by a single alphanumeric 
character. 

DCB: Required only if complete data 
control block information has not been 
specified in the processing program. 



DCB: Required only if complete data 
control block information has not been 
specified in the processing program. Data 
control block information is used when the 
data set is written on an intermediate mass 
storage volume and read by the output 
writer. However, the output writer's own 
DCB attributes are used when the data set 
is written on the system output device. 
Valid DCB parameters are listed in 
"Appendix C: Fields of the Data control 
Block." 

UNI T : Optional. An intermediate mass 
storage device is assigned if UNIT is 
specified. A default device is assigned if 
this parameter is omitted. 

SPACE: optional. Estimate the amount of 
mass storage space required. A default 
estimate is assumed if this parameter is 
omitted. 

Note: When a Direct SYSOUT Writer is used 
(OS/VS 1 only), the scheduler functions as a 
sequential scheduler. The SYSOUT data sets 
of the particular output class from any of 
the elegible job classes are not stored on 
an intermediate storage device, but are 
written directly to the system output 
device. When Direct SYSOUT Writer is used, 
all the parameters on the DD card are 
ignored. For detailed information on 
Direct SYSOUT Writer, see the publication 
0S/VS1 Planning and Use Guide . 



134 



Examples_of_DD__Statement s Used To Create Data Se ts 

The following examples show various ways of specifying DD statements 
for data sets that are to be created. In general, the number of 
parameters and subparameters that are specified depend on the 
disposition of the data set at the end of the job step. If a data set 
is used only in the job step in which it is created and is deleted at 
the end of the job step, a minimum number of parameters are required. 
However, if the data set is to be cataloged, more parameters should be 
specified. 



Exam ple It Creating a data set for the current job step only. 
//SYS0T1 DD UNIT=SYSDA,SPACE=(TRK, (50,10) ) 

This example shows the basic required DD statement for creating and 
storing a data set on a mass storage device. The UNIT parameter is 
reguired unless the unit information is available from another source. 
If the data set were to be stored on a unit record or a tape device, the 
SPACE parameter would not be needed. The operating system assigns a 
temporary data set name and assumes a disposition of (NEW, DELETE) . 



Example 2: Creating a data set that is used only for the current, job. 

//SYSLIN DD DSNAME=&&TEHP,DISP=(MOD,PASS) ,UNIT=SYSSQ, X 

// SPACE=(TBK, (50)) 

This example shows a DD statement that creates a data set for use in 
more than one step of a job. The system assigns a unigue symbol for the 
name, and this same symbol is substituted for each recurrence of the 
&&TEMP name within the job. The data set is allocated space on any 
available mass storage or tape device. If a tape device is selected, 
the SPACE parameter is ignored. The disposition specifies that the data 
set is either new or is to be added to (HOD) , and is to be passed to the 
next job step (PASS) . This DD statement can be used for specifying the 
data set that is created as output from the compiler and that is to be 
used as input to the linkage editor. By specifying MOD, separately 
compiled object modules can be placed in sequence in the same data set. 

Notet If SOD is specified for a data set that does not already exist, 
the job may be abnormally terminated when a volume reference name, a 
volume serial number, or the disposition CATLG is specified or when the 
dsname is indicated by a backwards reference. 
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Example 3: Creating a data set that is to be kept but not cataloged. 

//TEHPFILE DD DSN=FILEA,DISP= (, KEEP) , SPACE= <TRK , (30,10) ), X 

// UNIT=DIRECT,VOL=(, RETAIN, SEH=AA70) 

The example shows a DD statement that creates a data set that is kept 
but not cataloged. The data set name is FILEA. The disposition (,KEEP) 
specifies that the data set is being created in this job step and is to 
be kept. It is kept until a disposition of DELETE is specified on 
another DD statement. The KEEP parameter implies that the volume is to 
be treated as private, private implies that the volume is unloaded at 
the end of the job step but because RETAIN is specified, the volume is 
to remain mounted until the end of the job unless another reference to 
it is encountered. The DIRECT parameter is a hypothetical device class, 
containing only mass storage devices. The volume with serial number 
AA70, mounted on a device in this class, is assigned to the data set. 
Space for the data set is allocated as specified in the SPACE parameter. 
The data set has standard labels since it is on a mass storage volume. 

If the volume serial number were not specified in the foregoing 
example, the system would allocate space in an available nonprivate 
volume. Because KEEP is specified, the volume becomes private. 
(Another data set cannot be stored on a private volume unless its volume 
serial number is specified or affinity with a data set on the volume is 
stated.) The volume serial number of the volume assigned, if 
applicable, is included in the disposition message for the data set. 
Disposition messages are messages from the job scheduler, generated at 
the end of the job step. 



Exarople_4: Creating a data set and cataloging it. 

//DDNAMEA DD DSNAHE=INVENT. PARTS, DISP= (NEW, CATLG) , X 

// LABEL=(,,EXPDT=77031) ,UNIT=DACLASS, X 

// V0LUME=(,REF=*.STEP1.DD1) , X 

// SPACE=<C¥L, (5,1),,C0NTIG) 

This example shows a DD statement that creates a data set named 
INVENT. PASTS and catalogs it in the previously created system catalog. 
The data set is to occupy the same volume as the data set referred to in 
the DD statement named DD1 occurring in the job step named STEP1. The 
UNIT parameter is ignored since REF is specified. Five cylinders are 
allocated to the data set, and if this space is exhausted, more space is 
allocated, one cylinder at a time. The five cylinders are to be 
contiguous. The disposition (CATLG) , implies that the volume is to be 
private. The INVENT. PARTS is to have standard labels. The expiration 
date is the 31st day of 1977. 



Example 5: Adding a member to a previously created library. 
//SYSLHOD DD DSNAME=SYS1 . LINKLIB (INVENT) ,DISP=0LD 

This DD statement adds a member named INVENT to the link library 
(SYS1. LINK LIB) . When a member is added to a previously created data 
set, OLD should be specified. 
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Example 6; Creating a library and its first member. 

//SYSLMOD DD DSN AME=USERLI B (MYPROG) , DISP= {, CATLG) , X 

// SPACE=(TRK, (50,30,3)) , UNIT=3330 ,VOLUME=SER= 1 1 1 11 1 

This DD statement, creates a library, USERLIB, and places a member, 
MYPROG, in it. The disposition ( f CATLG) indicates that the data set is 
being created in this job step {NEW is the default condition for the 
DISP parameter and is indicated by the comma) and is to be cataloged. 
The data set is to have standard labels. Space is allocated for the 
data set in a volume on a mass storage device that is an IBM 3330 unit. 
Initially, 50 tracks are allocated to the data set, but when this space 
is exhausted, more tracks are added, 30 at a time. The SPACE parameter 
must be specified when the library is created, and it must include 
allocation of space for the directory. SPACE cannot be specified when 
new members are added. If additional space is reguired when new members 
are added, the secondary allocation, if specified, will be used. Three 
256-byte records are to be used for the directory. The volume serial 
number of the volume on which the library is to reside, is 111111. 



E xam pl e 7: Replacing a member of an existing library. 
//SYSLMOD DD DSN AME=MYLIB (CASE3) ,DISP=OLD 

This DD statement replaces the member named CASE3 with a new member 
with the same name. If the named member does not exist in the library, 
the member is added as a new member. In the foregoing example, the 
library is cataloged. 



Example 8: Creating and adding a member to a library used only for the 
current job. 

//SYSLMOD DD DSN AME=S&USERLIB(MYPROG) , DISP= (, PASS) ,UNIT=SYSDA, X 
// SPACE=(TRK, (50,, 1)) 

This DD statement creates and adds a member to a temporary library. 
It is similar to the DD statement shown in Example 6, except that a 
temporary name is used and the data set is not cataloged nor kept but is 
simply passed to the next job step. since the data set is to be used 
only for this one job, it is not necessary to specify VOLUME and LABEL 
information. This statement can be used for a linkage edit job step in 
which the module is to be passed to the next step. 

Note ; If DISP=(, DELETE) is specified for a library, the entire library 
will be deleted. 
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RETRIEVING PREVIOUSLY CREATED NON-VSAM DATA 
SETS 



The parameters that oust be specified in 
a DD statement to retrieve a previously 
created data set depend on the information 
that is available to the system about the 
data set. For example, 



If a data set on a magnetic-tape or 
mass storage volume was created and 
cataloged in a previous job or job 
step, all information for the data 
set, such as volume, space, etc., is 
stored in the catalog and data set 
label. This information need not be 
repeated. Only the dsname and 
disposition parameters need be 
specified. 



If the data set was created and kept 
in a previous job but has not been 
cataloged, information concerning the 
data set, such as space, record 
format, etc., is stored in the data 
set label. However, the unit and 
volume information must be specified 
unless available elsewhere. 



If the data set was created in the 
current job step, or in a previous job 
step in the current job, the 
information in the previous DD 
statement is available to the system 
and is accessible by referring to the 
previous DD statement. Only the 
dsname and disposition parameters need 
be specified. 



Note: A programmer may wish to change the 
previous disposition of a data set. For 
example, if KEEP was specified when the 
data set was created, the DD statement that 
retrieves the data set may change the 
disposition by specifying CATLG. 

Figure 49 shows the parameters that are 
used to retrieve previously created data 
sets. 



Retrieving C ata loged Dat a Se ts 



Input data sets, assigned a disposition 
of CATLG or cataloged by the IEHPRQGH 
utility program, are retrieved using the DD 
statement parameters DSNAME, DISP, LABEL, 
and DCB. The device type, volume serial 
number, and data set sequence number (if 
tape) are stored in the catalog. 
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Figure 49. Parameters Frequently Used in 
Retrieving Previously Created 
Data Sets 



DSNAME : Required. The data set must be 
identified by its cataloged name. If the 
catalog contains more than one index level, 
the data set name must be fully qualified. 

DISP: Required. The status (OLD or SHR) 
of the data set must be given and an 
indication made as to how it is to be 
treated after its use, unless it is to 
remain cataloged. The programmer can 
specify as the third term in the DISP 
parameter a conditional disposition to 
indicate how the data set is to be treated 
if the job step abnormally terminates. 

LABE L: Required only if the data set does 
not have a standard label. 

DCB: Required only if complete data 
control block information is not specified 
by the processing program and the data set 
label. To save recoding time, DCB 
attributes can be copied from an existing 
DCB parameter and modified if necessary. 
Valid DCB subparameters are listed in 
"Appendix C: Fields of the Data Control 
Block. » 

Note: In addition to the disposition 
UNCATLG, a cataloged data set can be passed 
to a later step {PASS) or deleted (DELETE). 
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Retr ieving Non c ataloqed fKE EP) D ata Sets 



Input data sets that were assigned a 
disposition of KEEP are retrieved by their 
tabulated name and location, using the DD 
statement parameters DSNAME, UNIT, VOLUME, 
DISP, LABEL, and DCB. 

DSNAME : Required. The data set must be 
identified by the name assigned to it when 
it was created. 

MIX" Reguired, unless VOLUME=HEF is used. 
The unit must be identified by its address, 
type, or group name. If the data set 
requires more than one unit, give the 
number of units. Deferred volume mounting 
and unit separation can be requested with 
this parameter. 

VOLUME: Required. The volume {s) must be 
identified with serial numbers or, if the 
data set was retrieved earlier in the same 
job, with VOLUME=REF. If the volume is to 
be PRIVATE, it must be so designated. If a 
private volume is to remain mounted until a 
later job step uses it, RETAIN should be 
designated. 

DISP: Required. The status (OLD or SHR) 
of the data set must be given and an 
indication made as to how it is to be 
treated after its use. The programmer can 
specify conditional disposition as the 
third term in the DISP parameter to 
indicate how the data set is to be treated 
if the job step abnormally terninates. 

LA3EL: Required if the data set does not 
have a standard label. If the data set 
resides with others on tape, its sequence 
number must be given. 

DCB: Reguired for all indexed sequential 
data sets. Otherwise, required only if 
complete data control, block information is 
not supplied by the processing program and 
the data set label. To save recoding time, 
copy DCB attributes from an existing DCB 
parameter, and modify them if necessary. 
Valid DCB subparameters are listed in 
Appendix C. 



Retrieving Passed Da ta Sets 



Input data sets used in a previous job 
step and passed are retrieved using the DD 
statement parameters DSNAME, DISP, and 
UNIT. The data set's unit type, volume 



location, and label information remain 
available to the system from the original 
DD statement. 

DSNAME : Required. The original data set 
must be identified by either its name or 
the DD statement reference term 
*.stepname.dd.name. If the original DD 
statement occurs in a cataloged procedure, 
the procedure stepname must be included in 
the reference terra. 

BISJ?: Required. Tbe data set must be 
identified as OLD, and an indication made 
as to how it is to be treated after its 
use. The programmer can specify 
conditional disposition as the third term 
in the DISP parameter to indicate how the 
data set is to be treated if the job step 
abnormally terminates. 

UNIT: Required only if more than one unit 
is allocated to the data set. 
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• The input stream can be on any device 
supported by QSAM. 

• Each job step and procedure step can be 
associated with several data sets in an 
input stream. All such data sets 
except the first in the job must be 
preceded by DD * or DD DATA statements. 



* The characters in the records 
coded in BCD or EBCDIC. 



iust be 



• If the data is preceded with a DD * 
statement, a /* delimiter following the 
data is optional. 
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Examples of DP Sta t e m en. t s_ U s ed to Retrie ve D ata Sets 



Example 1: Retrieving a cataloged data set. 

//CALC DD DSNAME=PRQCESS,DISP= (OLD, PASS, KEEP) 

This DD statement retrieves a cataloged data set named PROCESS. No 
UNIT or VOLUME information is needed. Since PASS is specified, the 
volume in which the data set is written is retained at the end of the 
job step. PASS implies that a later job step will refer to the data 
set. The last step in the job referring to the data set should specify 
the final disposition. If no other DD statement refers to the data set, 
it is assumed that the status of the data set is as it existed before 
this job. In the event of an abnormal termination, the KEEP disposition 
explicitly states the disposition of the data set. 



Example 2: Retrieving a data set that was kept but not cataloged. 

//TEMPFILE DD DSNAME=FILEA,UNIT= DIRECT, VOLUME=SER=AA70, DISP=0LD 

This DD statement retrieves a kept data set named FILEA. (This data 
set is created by the DD statement shown in Example 3 for creating data 
sets.) The data set resides on a device in a hypothetical device class, 
DIRECT. The volume serial number is AA70. 



Example 3: Referring to a data set in a previous job step, 

//SAMPLE JOB 

//STEP1 EXEC PGM=IKFCBL00,PARM=D3CK 



//SYSLIN DD DSNAME=ALPHA,DISP= (NEW, PASS) ,UNIT=SYSSQ 

//STEP2 EXEC PGK=IEWL 

//SYSLIN DD *. STEP1. SYSLIN, DISP= (OLD, DELETE) 

The DD statement SYSLIN in STEP2 refers to the data set defined in 
the DD statement SYSLIN in STEP1. 



Example »; Retrieving a member of a library. 

//BANKING DD DSNAME=P AYROLL (HOURLY) ,DISP=OLD 

The DD statement retrieves a member, HOURLY, from a cataloged 
library, PAYROLL. 
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DD STATEMENTS THAT SPECIFY UNIT RECORD 
DEVICES 



A DD statement say simply indicate that 
data follows in the input stream or that 
the data set is to be punched or printed. 
Figure 50 shows the parameters of special 
interest for these purposes. 



Ex ampl e 3: Specifying a card punch. 

//SYSP0NCH DD SYS0UT=B 

B is the standard device class for punch 
devices. 



CATALOGING A DATA SET 
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A data set is cataloged whenever CATLG 
is specified in the DISP parameter of the 
DD statement that creates or uses it. This 
means that the name and volume 
identification for the data set are placed 
in a system index called the catalog. {See 
"Processing with QISAM" in the section 
"Execution Time Data Set Requirements" for 
information about cataloging indexed 
sequential data sets.) The information 
stored in the catalog is always available 
to the system; conseguently , only the data 
set name and disposition need be specified 
in subsequent DD statements that retrieve 
the data set. See Example 4 in "Creating 
Non-VSAM Data Sets," and Example 1 in 
"Retrieving Non-VSAM Data Sets." 

If DELETE is specified for a cataloged 
data set, any reference to the data set in 
the catalog is deleted unless the DD 
statement containing DELETE retrieves the 
data set in some way other than by using 
the catalog. If UNCATLG is specified for a 
cataloged data set, only the reference in 
the catalog is deleted; the data set itself 
is not deleted. 



Example 1: 
reader. 



Specifying data in the card 



Note: A "cataloged data set" should not be 
confused with a "cataloged procedure" {see 
"Using the Cataloged Procedures") . 



GENERATION DATA GROUPS 



//SYSIN 



DD * 



The asterisk indicates that data follows 
in the input stream. The data must be 
followed by a delimiter statement if it 
contains // or /* in columns 1 and 2. 



Example 2 : Specifying a printer data set. 



//3YSPRINT DD SYS0UT=A 



SYSOUT is the system output parameter; A 
is the standard device class for printer 
data sets. 



It is sometimes convenient to save data 
sets as elements or generations of a 
generation data group (DSNAME=dsname 
(element)). A generation data group is a 
collection of successive, historically 
related data sets. Identification of data 
sets that are elements of a generation data 
group is based upon the time the data set 
is added as an element. That is, a 
generation number is attached to the 
generation data group name to refer to a 
particular element. The name of each 
element is the same, but the generation 
number changes as elements are added or 
deleted. The most recent element is 0, the 
element added previous to is -1, the 
element added previous to -1 is -2, etc. A 
generation data group must always be 
cataloged. 
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For example, a data group named PAYROLL 
might be used for a weekly payroll. The 
elements of the group are: 

PAYROLLJO) 
PAYR0LL<-1) 
PAYROLL (-2) 

where PAYROLL (0) is the data set that 
contains the information for the most 
current weekly payroll, and is the most 
recent addition to the group. 



When a ne 
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greater than 
new element 
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w element is added, it is 
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1) ; at the end of the job the 
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was PAYROLL <0) at the 

the job becomes PAYROLL (-1) at 
he job, and so on. 



If more than one element is being added 
in the same job, the first is given the 
number (+1), the next (+2) and so on. 



NAMING DATA SETS 



Each data set must be given a name. The 
name can consist of alphanumeric characters 
and the special characters, hyphen and the 
+0 {12-0 multipunch) . The first character 
of the name must be alphabetic. The name 
can be assigned by the system, it can be 
given a temporary name, or it can be given 
a user-assigned name. If no name is 
specified on the DD statement that creates 
the data set, the system assigns to the 
data set a unique name for the job step. 
If a data set is used only for the duration 
of one job, it can be given a temporary 
name (DSNAME=S&name) . If a data set is to 
be kept but not cataloged, it can be given 
a simple name. If the data set is to be 
cataloged it should be given a fully 
qualified data set name. The fully 
qualified data set name is a series of one 
or more simple names joined together so 
that each represents a level of 
qualification. For example, the data set 
name DEPT999. SMITH. DAT A3 is composed of 
three simple names that are separated by 
periods to indicate a hierarchy of names. 
Starting from the left, each simple name 
indicates an index or directory within 
which the next simple name is a unigue 
entry. The rightmost name identifies the 
actual location of the data set. 



each other. Including all simple names and 
periods, the length of a data set name must 
not exceed 44 characters. Thus, a maximum 
of 21 qualification levels is possible for 
a data set name. 

Programmers should not use fully 
qualified data set names that begin with 
the letters SYS and that also have a P as 
the nineteenth character of the name. 
Under certain conditions, data sets with 
the above characteristics will be deleted. 



EXTENDING NON-VSAM DATA SETS 



A processing program can extend an 
existing data set by adding records to it. 
If the EXTEND phrase of the OPEN statement 
is specified (QSAM data sets only) , COBOL 
positions the data set immediately 
following the last logical record. 
Subsequent WRITE statements then add 
records as though the data set had been 
opened with the OUTPUT phrase. (If LINAGE 
was specified, the initial position at the 
time of the OPEN EXTEND is assumed to be at 
the beginning of a page.) The DD statement 
for the data set to be extended need be no 
different than for a normal COBOL output 
file. Although the user need not specify 
DISP^MOD on the DD statement, the system 
implements the EXTEND request as if it had 
been; consequently, any system restrictions 
for DISP=MOD also apply to the EXTEND file. 

When OPEN EXTEND is not specified in the 
COBOL program, a sequential data set (QSAM 
or other) can still be extended by 
including DISP=MOD on the DD statement for 
the data set's retrieval. When MOD is 
specified, the system positions the 
appropriate read/write head after the last 
record in the data set. 

If a disposition of CATLG for an 
extended data set that is already cataloged 
is indicated, the system updates the 
catalog to reflect any new volumes caused 
by the extension. When extending a 
multivolurae data set where number of 
volumes might exceed the number of units 
used, the programmer should either specify 
a volume count or deferred mounting as part 
of the volume information. This ensures 
data set extension to new volumes. 



ADDITIONAL FILE PRO CESSING INFORMATION 



Each simple name consists of one to 
eight characters, the first of which must 
be alphabetic. The special character 
period {.) separates simple names from 



The following topics are discussed in 
this section: the data control block, 
error processing for COBOL files, and 
volume and data set labels. 
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More information about input/output 
processing is contained in the publication 
QSZ3ES-&ataJia.Paqeaent Services Guide. 



DATA CONTROL BLOCK 



Each non-VSAM data set is described to 
the operating system by a data control 
block (DCB). A data control block consists 
of a group of contiguous fields that 
provide information about the data set to 
the system for scheduling and executing 
input/output operations. The fields 
describe the characteristics of the data 
set (e.g., data set organization) and its 
processing requirements (e.g., whether the 
data set is to be read or written) . The 
COBOL compiler creates a skeleton DCB for 
each data set and inserts pertinent 
information specified in the Environment 
Division, PD entry, and input/output 
statements in the source program. The DCB 
for each file is part of the object module 
that is generated. Subsequently, other 
sources can be used to enter information 
into the data control block fields. The 
process of filling in the data control 
block is completed at execution time. 

Additional information that completes 
the DCB at execution time may come from the 
DD statement for the data set and, in 
certain instances, from the data set label 
when the file is opened. 



Ide ntifying DCB Information 



The links between the DCB, DD statement, 
data set label, and input/output statements 
are the filename, the system name in the 
ASSIGN clause of the SELECT statement, the 
ddname of the system-name, and the dsname 
(Figure 51). 

1. The filename specified in the SELECT 
statement and in the FD entry of the 
COBOL source program is the name 
associated with the DCB. 

2. Part of the system-name specified in 
the ASSIGN clause of the source 
program is the ddname link to the DD 
statement. This name is placed in the 
DCB. 

3. The dsname specified in the DD 
statement is the link to the physical 
data set. 

The fields of the data control block are 
described in the tables in Appendix C. 
They identify those fields for which 
information must be supplied by the source 
program, by a DD statement, or by the data 
set label. For further information about 
the data control block, see the discussion 
of the DCB macro instruction for the 
appropriate file processing technique in 
the publication OS/vs Data Manage ment 
Services Guide . 



Overr i ding DCB Field s 



Once a field in the DCB is filled in by 
the COBOL compiler, it cannot be 
overriddenby a DD statement or a data set 
label. For example, if the buffering 
factor for a data set is specified in the 
COBOL source program by the RESERVE clause, 
it cannot be overridden by a DD statement. 
In the same way, information from the DD 
statement cannot be overridden by 
information included in the data set label. 




Figure 51. Links between the SELECT Statement, the DD Statement, the Data Set Label, and 
the Input/Output Statements 
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ERfiOR PROCESSING FOR NGN-VSAH COBOL FILES 

The actions taken after an I/O error depend 
on a number of things : 

* What access method is being used 

• What type of error it is 

• What sort of error handling 
statements the program contains 
(if any) 

* For certain error types on a 
QSAM file, what DCB EROPT 
s'Jbparameter was specified 

If an error declarative, a file status 
clause, or an invalid key clause is 
specified for a particular file, the 
DCBSYNAD field of the data control block 
for that file contains the address of an 
entry point in ILBOSYNO (COBOL* s error 
intercept library subroutine) . ILBOSYNO 
has 5 entry points (ILB0SYN1, 2, 3, 4, 
and 5) corresponding to each of the five 
access methods supported (other than 
VSAM) ; they are QSAM, BSAM, BDAM, 
QISAM, and BISAM. If no error declarative, 
file status clause, or invalid key clause 
is specified, no SYNAD routine is 
activated and the appropriate system 
action is taken. 

In general, error handling for BSAM, 
QISAM, BDAM, and BISAM is identical. 
Figure 52 shows what happens when the 
access method has detected an error and 
given control to the COBOL SYNAD 
routine. The program will either continue 
at the next statement following the 
I/O statement that caused the error, or 



abend — depending on the type of error 
and the error handling language in the 
program. 

Error handling for QSAM files, however, is 
different and more complex, because of these 
additional factors: 

1 . The choice of EROPT subparameter (whether 
ACC, SKP, or ABE) affects some conditions 

2. The presence or absence of a FILE STATUS 
clause affects most conditions 

3. COBOL itself does some error checking, 
and handles conditions it finds 
differently 

Figure 53 shows this logic flow. Note that 
there are three general possibilities, 
depending on whether the error is a 
QSAM-detected space problem, some other 
type of QSAM-detected problem, or a 
COBOL-detected problem. Errors in the 
last category are such things as OPEN and 
CLOSE failures , attempts to 'read/write/rewrite 
on an unopened file, attempts to read past 
end-of-file, and the like. (These are errors 
that would fall into the FILE STATUS 
classifications of 90 or higher.) A program 
encountering an error on a QSAM file will 
continue, abend, or terminate the job step 
with a return code of 12. 
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BSAM 




QISAM 




BDAM 




BISAM 


1-0 ERROR 




1-0 ERROR 




1-0 ERROR 




1-0 ERROR 


ILB0SYN2 




ILB0SYN3 




ILB0SYN4 




ILB0SYN5 


" 


" 










" 

















YES / EXIT TO 

*►( ERROR 

\DECLARAJIVE 



RETURN TO 
SYSTEM* 



ISSUE 

SYNADADF 
AND FORMULATE 
ERROR MESSAGE 



'WRITE 
ERROR 
MESSAGE ON 
CONSOLE 
ANDSYSOUTj 



(TERMINATE A 
RUN UNIT J 



•EXECUTION OF COBOL PROGRAM THEN CONTINUES FOLLOWING THE I/O STATEMENT THAT RAISED THE ERROR. 



Figure 52. Flow of Control in COBOL After Error Detected on BSAM/QISAM/BDAM/BISAM I/O 
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SPACE NOT FOUND BY QSAM FOR 
WRITE OR CLOSE REEL/UNIT 
(INVALID KEY CONDITION - FILE 
STATUS KEY OF 34; EQUIVALENT 
TO x37 ABEND CODE) **' 



OTHER ERRORS 
DETECTED BY QSAM 




ON EXIT FROM DECLARATIVE, 
RETURN TO QSAM. IF EROPT= 
ACC/SKP, COBOL PROGRAM WILL 
THEN CONTINUE; IF EROPT=ABE, 
PROGRAM WILL BE ABENDED. 



(RETURN TO A 
QSAM* J 



ERROR DETECTED BY COBOL ITSELF 
(CONDITION EQUIVALENT TO FILE 
STATUS KEY OF 90 OR HIGHER) 




ISSUE SYNADAF 
AND MESSAGE 
IKF111I 



/FILES. 




^WRITES 


STATUS X 


YES 


S OR 


CLAUSE 




REWRITE 


.SPECIFIED/'' 




^SfEQUEST, 



/RETURN TO QSAm\ 
( WHICH ABENDS ) 
\ COBOL PROGRAM / 



ISSUE MESSAGE 
IKF115I, DO STOP 
RUN PROCESSING 



(RETURN TO SYSTEMS 
WITH RETURN CODE ) 
0F12 J 



"EXECUTION OF THE COBOL PROGRAM THEN CONTINUES FOLLOWING THE I/O 
STATEMENT THAT RAISED THE ERROR. 

"FILE STATUS KEY 34 IS NOT ISSUED FOR A SORT-GIVING FILE. 



Figure 53. Flow of Control in COBOL After Error Detected on QSAM I/O 
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CQBOL,3,an3q?qe,Fgaiures_for Input/Outfiot These language features are: the FILE 
tefQT Prggessiag STATUS clause, the INVALID KEY clause, and 

... a . , the USE AFTER EBHOR declarative. See IBM 
The COBOL programmer has at his disposal VS COBOL for nyvs for complete details~on 
several language features which enable him the proper use of these features, 
to be notified of an input/output error and 
its exact nature — information he can 
utilize to attempt a retry if possible. 
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FILE STATUS Key 

The FILE STATUS clause may be specified for 
QSAM files in order to provide a means of 
testing the success of individual I/O 
operations and determining more closely the 
specific nature of an error condition when 
it arises. QSAM FILE STATUS may be used 
alone, or in conjunction with the error 
declarative procedure (described below) . 
In the latter case, the FILE STATUS key is 
set by COBOL before the error declarative 
is given control. 



QSAM status key values are explained 
in the table below. 



INVALID KEY Option 

The INVALID KEY option, when specified, 
applies only for the specific input/output 
operation requested; when the operation is 
terminated successfully, the INVALID KEY 
clause is nullified. This means that the 
file has no constant INVALID KEY routine 
associated with it, but that the active 
INVALID KEY routine is the one specified on 
the current input/output verb. For files 
accessed randomly and for output files 
accessed sequentially, an INVALID KEY 
clause may be specified with the verbs 
READ, WRITE, and START. 



INVALID KEY conditions (those which pass 
control to INVALID KEY clauses) , as 
interpreted by COBOL, vary with the access 
method used, but may be generally described 
as follows: record not found, duplicate 
record, and sometimes space for output not 
found. 

The Er ror De cla r ativ e 

A single USE AFTER STANDARD ERROR 
declarative defines, for a certain subset 
of the files within a COBOL program, a 
series of operations to be performed for 
the express purpose of determining the 
exact nature of an input/output error and 
attempting to recover from that error. 
This series of operations may cover as 
broad or restrictive a subset of the files 
as the programmer wishes. A single 
declarative may be applied to all OUTPUT, 
all INPUT, or all 1-0 files, a single file, 
or any number of files; it is the 
programmers responsibility to ensure no 
conflict of applicability arises. 

For example, within the same program, a 
single file may be opened as OUTPUT, INPUT, 
and 1-0 at different states of processing. 
Three separate error declaratives may be 
coded for this file, since the proper 
declarative will be activated just before 
the file is opened. For additional 
information on declaratives, see I BH „ VS 
cobol fgr_os/ys . 



Note ; The INVALID KEY routine is given 
control only for input/output errors 
specifically attributed to an INVALID KEY 
condition; no return is made to the system 
from such a routine. Hence, this option 
merely informs the programmer that one of 
these conditions arose — this may be all 
he needs to know — and no direct return to 
the system is possible, nor is any further 
information on the nature of the error 
available at the COBOL source level. 



The declarative also offers a very 
potent and flexible tool for determining 
the nature of input/output errors; it is 
the GIVING option which may be specified 
for any of the subsets of files mentioned 
earlier. Within the GIVING clause, 
data-name- 1 is specified and will contain a 
136-byte descriptive error message after an 
input/output error on a READ, WRITE, 
REWRITE, or START verb. This field must 
reside in working storage. It will contain 
spaces for logic errors on QSAM files. 
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STATUS 


KEY 1 


STATUS 


KEY 2 


Value 



Meaning 

Successful completion 


Value 



Meaning 


No further information 


1 


At end (no next logical record, 
or an OPTIONAL file not available 
at OPEN time) 





No further information 


3 


Permanent error (data check, 
parity check, transmission error) 





No further information 






4 


Space not found to add requested 
output record; for example, file's 
extents could be exhausted 


9 


Other errors 





OPEN or CLOSE failed (OPEN 
failure could result from missing 
DD card) 






2 


Logic error; for example, attempt 
to open a file already open, 
attempt to open a file previously 
closed with a lock, attempt to 
close a file already closed or 
never successfully opened, 
attempt to read/write/rewrite on 
an unopened file or a file opened 
in the wrong mode (e.g., WRITE on 
file opened INPUT) , attempt to 
read after end-of-file has been 
reached 



Data-name-2 can be specified optionally 
and will contain the block in error if data 
transfer actually took place; this 
restricts its applicability to input 
operations — specifically, READs. 
Data-name-2 may be defined in the 
Working-Storage Section or in the Linkage 
Section. Defining it in the 
Working-Storage Section requires that 
enough storage be reserved within the 
program* s data area to contain the block in 
question. The block will be moved into 
data-name-1 from the buffer if the system 
indicates data transfer did take place; 
otherwise, no move will be executed. 
Defining data-name-2 in the Linkage Section 
results in space being reserved within the 
object program only for 4 bytes per UK 
bytes of the block ; the block is 
referenced in the buffer by means of these 
cells. 

Besides storage and performance 
considerations, one reason for defining 
data-name-2 in the Linkage Section is that 
data-name-1 should be examined thoroughly 



before any reference to data-name-2 is 
made. For example, if a declarative 
specified for a single file, which is 
opened INPUT and OUTPUT, within the program 
is entered because an input/output error 
occurred on a WHITE verb for that file, an 
attempt to access data-name-2 will result 
in an abnormal termination. Data-name-1 
should be checked for input/output 
operation, access method, block address, 
and so on, before data-name-2 is referenced 
at all. Figure 54 shows an example of this 
type of checking. 

Figure 54 shows a single error 
declarative which has been specified for 
two files, one QSAM assigned to tape and 
one BISAH. For simplicity, processing of 
each file is kept separate in the 
declarative, even though some common 
processing could have been done. Each file 
has the same logical record length; if they 
had different lengths, a problem might 
arise when the entry coding of the 
declarative attempts to move the offending 
block into data-name-2. 



User Non-VS&M File Processing 149 



00001 
C0002 
C0003 
C0004 
00005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
00014 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00024 
C0025 
00026 
00027 
00028 
00029 
00030 
00031 
00032 
00033 
00034 
00035 
00036 
00037 
00038 
00039 
00040 
00041 
00042 
00043 
00044 
00045 
00046 
00047 
00048 
00049 
00050 
00051 
00052 
00053 
00054 
00055 
00056 
00057 



IDENTIFICATION DIVISION. 
REMARKS. 

THIS PROGRAM CAUSES 1-0 ERRORS FOR A QSAM AND ISAM FILE AND 

WILL DEMONSTRATE THE USE OF THE ERROR DECLARATIVE. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT QSAM-FILE, 

ASSIGN TO UT-S-QSAMFILE. 

SELECT BISAM-FILE, 

ASSIGN TO DA-I-BISMFILE, 
ACCESS IS RANDOM, 
NOMINAL KEY IS NOMINAL-KEY, 
RECORD KEY IS RECORD-KEY. 
DATA DIVISION. 
FILE SECTION. 
FD QSAM-FILE, 

RECORDING MODE IS F f 

LABEL RECORDS ARE OMITTED, 

RECORD CONTAINS 100 CHARACTERS, 

DATA RECORD IS QSAM- RECORD. 
01 QSAM-RECORD PIC X(100). 
FD BISAM-FILE, 

RECORDING MODE IS F, 

LABEL RECORDS ARE STANDARD, 

RECORD CONTAINS 80 CHARACTERS, 

DATA RECORD IS BISAM-RECORD. 
01 BISAM-RECORD. 

05 FILLER PIC X. 

05 RECORD-KEY PIC X(5). 

05 FILLER PIC X(74). 
WORKING-STORAGE SECTION. 
01 SYNAD- RECORD COPY ERRSRCD1. 
01 SYNAD-RECORD. 
► 

»■ THIS RECORD IS FORMATTED TO SHOW ALL FIELDS IN DATA-NAME-1 
" (THE SYNADAF MESSAGE). NOT ALL FIELDS WILL BE REFERENCED 
" IN A PARTICULAR PROGRAM. 



05 
05 
05 
05 
05 
05 
05 
05 
05 
05 
05 



05 
05 
05 
05 



FILLER PIC X(8). 

INPUT- BUFFER- ADDRESS PIC X(4). 

NUMBER-OF- BYTES-READ PIC 9(4) USAGE COMP. 

FILLER PIC X(36). 

JOBNAME PIC X(8). 

FILLER PIC X. 

STEPNAME PIC X(8). 

FILLER PIC X. 

UNIT-ADDRESS PIC X(3). 

FILLER PIC X. 

DEVICE-TYPE PIC XX. 

88 MASS- STORAGE-DEVICE VALUE , DA*. 

88 MAGNETIC-TAPE-DEVICE VALUE " TA* . 

88 UNIT- RECORD-DEVICE VALUE , URV. 

FILLER PIC X. 

DDNAME PIC X(8). 

FILLER PIC X. 

OPERATION- ATTEMPTED PIC X(6). 



Figure 54. Example of Use of GIVING Option in Error Declarative (Part 1 of 3) 
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00058 
00059 
00060 
00061 
00062 
00063 
00064 
00065 
00066 
00067 
00068 
00069 
00070 
00071 
00072 
00073 
00074 
C0075 
00076 
00077 
00078 
00079 
00080 
00081 
00082 
00083 
00084 
00085 
00086 
00087 
00088 
00089 
00090 
00091 
00092 
00093 
00094 
00095 
00096 
00097 
00098 
00099 
00100 
00101 
00102 
00103 



05 FILLER PIC X. 

05 ERROR- DESCRIPTION PIC X(15). 

88 WLR- ERROR VALUE »WRNG. LEN. RECORD* . 
88 INVLD-REQ VALUE • INVALID REQUEST*. 
05 FILLER PIC X. 
05 ACCESS-METHOD-DATA. 
10 UNIT-RECORD. 

15 FILLER PIC X(15). 
15 UR-ACCESS-METHOD PIC X(6). 
10 MAGNETIC-TAPE REDEFINES UNIT-RECORD. 
15 RELATIVE- BLOCK-NUMBER PIC 9(7). 
15 FILLER PIC X. 
15 T A- ACCESS-METHOD PIC X(5). 
15 FILLER PIC X(8). 
10 MASS-STORAGE REDEFINES UNIT-RECORD. 
15 LAST-ACTUAL-ADDRESS PIC X (14). 
15 FILLER PIC X. 
15 DA- ACCESS-METHOD PIC X(6). 
05 SYSTEM- USE PIC X(8). 
01 NOMINAL- KEY PIC 9(5). 
LINKAGE SECTION. 
01 ERROR- DATA PIC X(100). 
PROCEDURE DIVISION. 
DECLARATIVES. 
ERROR- EXAMPLE SECTION. 

USE AFTER STANDARD ERROR PROCEDURE 
ON QSAM-FILE, BISAM-FILE, 
GIVING SYNAD-RECORD, ERROR-DATA. 
DISPLAY •** ERROR DECLARATIVE ENTERED FOR" 

OPERATION- ATTEMPTED • OPERATION **". 
DISPLAY SYNAD-RECORD. 

IF ERROR- DESCRIPTION IS NOT EQUAL TO 'UNKNOWN COND 1 
AND 
OPERATION- ATTEMPTED IS NOT EQUAL TO "UNKNOWN" 
GO TO DECLARATIVE- 1. 
K 

* IF OPERATION OR ERROR TYPE IS UNKNOWN, CALL ASSEMBLY 
"■ LANGUAGE ROUTINE TO CHECK MORE DEEPLY. 

K 

IF DA-ACCESS-METHOD IS EQUAL TO * QSAM * , 
CALL •ERRANAL', 

USING SYSTEM-USE, QSAM-FILE, ACCESS- METHOD- DATA; 
ELSE 

CALL •ERRANALV, 

USING SYSTEM-USE, BISAM-FILE, ACCESS-METHOD-DATA. 
GO TO DECLARATIVE-EXIT. 



Figure 54. Example of Use of GIVING Option in Error claratve (Part 2 of 3) 
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00119 




00120 
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00121 
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00122 
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00128 




00129 




00130 




00131 




00132 




00133 




00134 




00135 




00136 




00137 




00138 




00139 




00140 




00141 




00142 




00143 




00144 





DECLARATIVE-1. 

CHECK EXPECTED QSAM OR BISAM ERROR CONDITION. 

IF WLR-ERROR. 

DISPLAY •** WRONG LENGTH RECORD ERROR AS EXPECTED **', 

GO TO declarative-exitA 



CHECK ONE PARTICULAR ERROR POSSIBILITY, 
IN ERROR IF POSSIBLE, THEN EXIT. 



THEN DISPLAY BLOCK 



IF DA- ACCESS-METHOD IS NOT EQUAL TO "BISAM* , 

GO TO DECLARATIVE- 2. 
IF NOT INVLD-REQ, 

GO TO DECLARATIVE-EXIT. 

BISAM INVALID REQUEST. EXIT DECLARATIVE VIA "GO TO". 

CLOSE BI SAM-FILE. 
GO TO PROCESS-NEXT-FILE. 
DECLARATIVE- 2. 

IF INPUT-BUFFER- ADDRESS IS EQUAL TO SPACES, 
CLOSE QSAM-FILE, 
GO TO PROCESS- BISAM-FILE. 
DISPLAY ERROR-DATA. 
DECLARATIVE-EXIT. 

EXIT. 
END DECLARATIVES. 

OPEN INPUT QSAM-FILE. 
READ QSAM-FILE, 
AT END 

CLOSE QSAM-FILE, 
STOP RUN. 
PROCESS-BISAM-FILE. 

OPEN 1-0 BISAM-FILE. 
MOVE 100 TO NOMINAL- KEY. 
REWRITE BI SAM-RECORD. 
CLOSE BISAM-FILE. 
PROCESS-NEXT-FILE. 
STOP RUN. 



Figure 54. Example of Use of GIVING Option in Error Declarative (Part 3 of 3) 
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Since it is the receiving field, the length 
of data-name-2 is taken as the length of 
the move. Therefore, when using the same 
error declarative for files, ensure the 
files do not haye differing attributes. 

SYNAD- RECORD, a 136-byte area set aside 
to receive the error message provided by 
the system, is compatible across all access 
methods. An area of some variation is 
ACCESS-METHOD-DATA, which is device 
dependent. SYNAD-RECORD is shown in great 
detail for the purpose of showing how each 
field might be coded, such exhaustive 
detail, however, is not necessary in many 
applications, and only the fields to be 
referenced need be explicitly described at 
all. This detailed map of the area would 
be a good skeleton for a COPY library 
member, once it is standardized for an 
installation. 

When data has been transferred, 
INPUT-BUFFER-ADDRESS will contain the 
address of such data and is the source of 
data-name-2. Likewise, 

NUMBER-OF-BYTES-READ contains the actual 
length of the offending block. DEVICE-TYPE 
is a key to the actual layout of 
ACCESS-METHOD-DATA, which is device 
dependent. The possible content of 
OPERATION-ATTEMPTED, ERROR-DESCRIPTION, and 
ACCESS-METHOD-DATA are shown in some detail 
in Appendix G. SYSTEM-USE is an 8-byte 
field which is not useful to a COBOL source 
program but which in most cases reflects 
the contents of registers and 1 upon 
entry to the SYNAD routine and are passed 
as arguments (shown at line 100 in Figure 
54) to the assembly language program 
ERRANAL for further study. The user will 
find additional information about the 
contents of this field in OS/VS Data 
Man agement Macro I nstr ucti ons. 

Notje: Data-name-2, ERROR-DATA in the 
example, is specified in the Linkage 
Section; the generated code within the 
declarative will do nothing but move the 
address of INPUT-BUFFER- AD DRESS into a base 
locator cell assigned to ERROR-DATA. 

Immediately upon entry to the declarative, 
a signal message is displayed as well as 
the SYNAD-RECORD. Then if an unknown 
operation or error is indicated in the 
message, the system calls ERRANAL passing 
SYSTEM-USE, the appropriate DCB or DECB, 
and ACCESS-METHOD-DATA, exiting from the 
declarative upon return. 

If both fields are known, the system 
does further checking. For the purpose of 
this example, it is assumed that a 
wrong- length record is expected and this 
causes a message to be printed and an exit 
from the declarative. Finally, for the 
BISAM file, the coding checks the invalid 



request condition. If invalid, the file is 
closed and the declarative is exited via a 
GO TO statement {not a normal exit). If it 
is a QSAM file, the field containing the 
address of the data represented by 
data-name-2 is checked for blanks before 
displaying it. For a QIS&M file, 
data-narae-2 can never be referenced. 

This example of error declarative 
technique points out some basic tools: the 
use of fields within data-name- 1 to decide 
processing; the checking of the address 
used for data-name-2 before referring to 
it; the use of data-name- 1 as a group item; 
the normal and GO TO exits from the 
declarative; the calling of an assembly 
language subroutine to perform detailed 
analysis of system information; forcing use 
of a declarative for INVALID KEY conditions 
by not coding an INVALID KEY clause; 
closing of the offending file if the nature 
of the error suggests such an action. A 
course of action not described here (but 
often possible) is a retry of the 
input/output operation that caused the 
error. 

The INVALID KEY clause and/or the error 
declarative may be specified for a file, 
and for any given input/output error, the 
error intercept subroutine decides which is 
to be given control. Figure 55 is a 
generalized summary of the means available 
for recovery from an invalid key condition 
or an input/output error. 



It is most imp 
make certain of t 
before referencin 
complete message 
the system, the e 
declarative takes 
block in error in 
the Working-Stora 
the base locator 
Linkage Section. 



ortant that the programmer 
he validity of data-name-2 
g it. In the event that a 
could not be formatted by 
ntry coding in the error 

steps to avoid moving the 
to data-name-2 if it is in 
ge Section or setting up 
address if it is in the 



However, it is up to the user to avoid 
an invalid reference. Note also that for 
certain conditions, the contents of 
data-name-1 will be invalid {blanks or 
asterisks) . The user may find information 
on this under SYNADAF macro in O S /VS Data 
Management Macro .I ns tructions. 

Note: The programmer should also consider 
the following when a relatively large 
number of INVALID KEY exits or declarative 
sequences (with GO TO exits) are to be 
executed: 

1. The distinction between error 

processing via an error declarative 
and the the INVALID KEY clause. When 
an input/output operation is 
requested, a storage area of about 40 
to 100 bytes (called an input/output 
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block or IOB) is al 
reguest is satisfie 
of an error, until 
user- provided error 
If the error declar 
normal exit from th 
returns control the 
the IOB. 8hen the 
is used, however, t 
regain control and 
freed. 



located until the 
3 (or, in the event 
return from the 
-handling routine) . 
ative is used, a 
e declarative 

system and frees 
INVALID KEY routine 
he system does not 
the IOB is not 



VOLUME LABELING 



Various groups of labels may be used in 
secondary storage to identify magnetic-tape 
and mass storage volumes, as well as the 
data sets they contain. The labels are 
used to locate the data sets and are 
identified and verified by label processing 
routines of the operating system. 



No te: If an I/O error occurs on a 
WRITE or HEWRITE, and a FILE STATUS 
clause was specified but an error 
declarative or INVALID KEY clause was 
not, then the system does not regain 
control and the IOB is not freed. 



The error declarative interface 
dynamically allocates storage for a 
register save area upon entry, roughly 
200 bytes. This is necessary to make 
the declarative serially reusable in 
the event of another input/output 
error occurring within the 
declarative, and for which it is 
specified (for example, an I/O reguest 
to another file may be done within the 
declarative, and this second attempt 
may also cause an error). If a GO TO 
statement is used to exit from the 
declarative, neither this save area 
nor the IOB is freed. 

To make maximum efficient use of one's 
address space and to make the maximum 
space available to other users, the 
programmer should rely on the error 
declarative as much as possible, 
taking a normal exit from it. 
Otherwise, it is recommended that the 
programmer specify a larger address 
space. 



There are two different kinds of labels, 
standard and nonstandard. Magnetic tape 
volumes can have standard or nonstandard 
labels, or they can be unlabeled. The 
type(s) of label processing for tape 
volumes to be supported by an installation 
is selected during the system generation 
process. Mass storage volumes are 
supported with standard labels only. 



Standard labels consist of volume labels 
and groups of data set labels. The volume 
label group precedes or follows data on the 
volume; it identifies and describes the 
volume. The data set label groups precede 
and follow each data set on the volume, and 
identify and describe the data set. 

• The data set labels that precede the 
data set are called header labels. 

• The data set labels that follow the 
data set are called trailer labels. 
They are almost identical to the header 
labels. 

• The data set label groups can 
optionally include standard user labels 
except for ISAM files. 

• The volume label groups can optionally 
include standard user labels for QSAM 
files. 
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Figure 55. Recovery from an Invalid Key Condition or other Input/Output Error (Non-QSAM) 
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1. Holds only for WRITE. 

2. Error cannot be caused by an invalid key. 

Figure 56. Input/Output Error Processing Facilities (Non-QSAM) 
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Specific information about the contents 
and physical location of labels is 
contained in the publications QS/VS pata 
Management Ser v ices Guide and OS/VS Tape 
Labels. 



The format of the ma 
label group is the same 
the tape volume label g 
the data set labels of 
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STANDARD USER LABELS 



STANDARD LABEL FOR WAT 



Standard labels are 80-character records 
that are recorded in EBCDIC and odd parity 
on 9-track tape; or in BCD and even parity 
on 7 -track tape. The first four characters 
are always used to identify the labels. 
These identifiers are: 



V0L1 

HDR1 and HDR2 — 

E0V1 and E0V2 — 

E0F1 and EOF 2 — 

UHL1 to DHL8 

UTL1 to 0TL8 



volume label 
data set header 
labels 

data set trailer 
labels {end-of-volume) 
data set trailer labels 
(end-of-data set) 
user header labels 
user trailer labels 



Standard user labels contain 
user-specified information about the 
associated data set. User labels are 
optional within the standard label groups. 
The format used for user header labels 
(UHL1-8) and user trailer labels (UTL1-8) 
consists of a label 80 characters in length 
recorded in EBCDIC on 9-track tape units, 
or in BCD on 7-track tape units. The first 
three bytes consist of the characters that 
identify the label: UHL for a user header 
label (at the beginning of a data set) or 
UTL for a user trailer label (at the 
end-of-volume or end-of-data set) . The 
next byte contains the relative position of 
this label within a set of labels of the 
same type and can be any number from 1 
through 8. The remaining 76 bytes consist 
of user- specified information. 
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User labels are generally created, 
examined, or updated when the beginning or 
end of a data set or volume (reel) is 
reached. User labels are applicable for 
sequential, direct, and relative data sets. 
For sequentially processed data sets, end 
or beginning of volume exits are allowed 
(i.e., "intermediate" trailers and headers 
may be created or examined). For direct or 
relative data sets, user laael routines 
will be given control only during OPEN or 
CLOSE condition for a file opened as INPUT, 
OUTPUT, or I-Q. Trailer labels for files 
opened as INPUT or 1-0 are processed when a 
CLOSE statement is executed for the file 
that has reached an AT END condition. 
Thus, for physical sequential data sets, 
the user may create, examine, or update up 
to eight header labels and eight trailer 
labels on each volume of the data set, 
whereas for direct or relative data sets 
the user may create, examine, or update up 
to eight header labels during OPEN and up 
to eight trailer labels during CLOSE. 
(QSAM EXTEND functions in a manner 
identical to OUTPUT, except that the 
beginning of a file label is not 
processed.) Note that these labels reside 
on the initial volume of a multi-volume 
data set. This volume must be mounted at 
CLOSE if trailer labels are to be created, 
examined, or updated. 
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this way, he can tell exactly what records 
were written. This information can also be 
used for accurately labeling tape reels 
(i.e., assigning physical adhesive labels). 

To request this option, specify OPTCD=T 
in the DCB parameter of the DD statement. 
The user's TOTALING area, where control 
data is accumulated, is provided by the 
user. In this area, the user can store 
information on each record he writes. When 
an input/output operation is scheduled, the 
control program sets up a user TOTALED save 
area that preserves an image of the 
information in the user's TOTALING area. 
When the output USE LABEL declarative is 
entered, the values accumulated in the 
user's TOTALING area corresponding to the 
last record actually written on the volume 
are stored in the TOTALED area. These 
values can be included in user labels. 
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User label totaling is not available 
with S-raode records. 



H ser Label T otaling 
(BSAfi and OSAM only) 

When creating or processing a data set 
with user labels on a sequential file, the 
programmer may develop control totals to 
obtain exact information about each volume 
of the data set. This information can be 
stored in his user labels. For example, a 
control total accumulated as the data set 
is created, can be stored in a user label 
and later compared with a total accumulated 
while processing a volume. The user 
totaling facility enables the programmer to 
synchronize the control data that he has 
created while processing a data set with 
records physically written on a volume. In 



NONSTANDARD LABEL FORHAT 



Nonstandard labels do not conform to the 
standard label formats. They are designed 
by programmers and are written and 
processed by programmers. Nonstandard 
labels can be any length less than 4096 
bytes. There are no requirements as to the 
length, format, contents, and number of 
nonstandard labels, except that the first 
record on the volume cannot be a standard 
volume label. In other words, the first 
record cannot be 80 characters in length 
with the identifier VOL1 as its first four 
characters. 
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NONSTANDARD LABEL PROCESSING 



To use nonstandard labels (NSL) , the 
system programmer must first: 



• Create nonstandard label processing 
routines for input header labels, input 
trailer labels, output header labels, 
and output trailer labels. 

• Insert these routines into the 
operating system. 

Then the COBOL programmer must code NSL in 
the LABEL parameter of the DD statement at 
execution time. 

The system verifies that the tape has a 
nonstandard label. Then if N S L is 
specified in the LABEL parameter, it loads 
the appropriate NSL routines. These NSL 
routines are entered at OPEN, CLOSE, and 
END-OF-VOLUME conditions by the respective 
executors. 

For a data set opened as output, the NSL 
routines entered include: 

• At OPEN time, a header routine to check 
the old header and/or create the new 
header; 

• At CLOSE time, a trailer-creation 
routine; 

• At EOV time, a trailer-creation routine 
and a header routine. 

For a data set opened as input essentially 
the same types of routines are required. 



In addition, the NSL routines must write 
their own taperaarks, do all I/O operations 
necessary (via EXCP) , determine when all 
labels have been processed, and take care 
of data set positioning. These routines 
may communicate at the LABEL source level 
with USE BEFORE LABEL PROCEDURE 
declaratives by means of linkage described 
under "User Label Procedure." 



USER LABEL PROCEDURE 



The USE.. .LABEL PROCEDURE statement 
provides the user with label handling 
procedures at the COBOL source level to 
handle nonstandard or user labels. The 
BEFORE option indicates processing of 
nonstandard labels. The AFTER option 
indicates processing of standard user 
labels. The labels must be listed as 
data-names in the LABEL RECORDS clause in 
the File Description entry for the file. 
When the file is opened as input, the label 
is read in and control is passed to the USE 
declarative if a USE... LABEL PROCEDURE is 
specified for the OPEN option or for the 
file. If the file is opened as output, a 
buffer area for the label is provided and 
control is passed to the USE declarative if 
a USE... LA BEL PROCEDURE is specified for 
the OPEN option or for the file. For files 
opened as INPUT or 1-0, control is passed 
to the USE declarative to process trailer 
labels when a CLOSE statement is executed 
for the file that has reached the AT END 
condition. 



I2te: The NSL routines must observe the 
following conventions: 

1. Follow Type-IV SVC routine 
conventions. 

2. Use GETHAIN and FREEHAIN for work 
areas. 

3. Be reentrant load modules. 

4. Use EXCP for I/O operations and XCTL 
for passing control among load modules 
and then returning to the I/O-support 
routines. 

5. Begin with the letters NSJL if the 
system branches to them directly. 
(Other user-written modules having to 
do *ith nonstandard labels must begin 
with the letters IGC. ) 

6. Have as their entry points the first 
byte in each load module. 



One of the concerns of the programmer is 
linkage between the nonstandard label SVC 
routine and the USE BEFORE LABEL PROCEDURE 
section. Other problems related to writing 
nonstandard label SVC routines are 
discussed in the publication OS/VS__Tap_e 
Labels. 



When the nonstandard label SVC routine 
has determined that a particular DCB has 
nonstandard labels, the nonstandard label 
routine must inspect the DCB exit list for 
an active entry to ensure that there is a 
USE BEFORE. ..LABEL section for this DCB and 
for that type of label processing. The DCB 
field EXLST contains a pointer to this exit 
list. An active entry is defined as a 
1-byte code other than X^O' or X'80» 
followed by a 3-byte address of the 
appropriate label section (Figure 57) . 
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}Code 



I 1 



Exit List 



{USE section for header labels) 
(USE section for trailer labels) 



I Notes: 

J 1. Code 1 is set to X»01' indicating 
| INPUT, or X«02» indicating OUTPUT. 
| 2. Code 2 is set to « x'OD* indicating 
I INPUT, or X'04* indicating OUTPUT. 
i . 

Figure 57. Exit List codes 



Once the nonstandard label SVC routine 
tests that the exit list confirms an 
appropriate active entry, it must pass the 
address of a parameter list in register 1. 



The parameter list (Figure 58) must have 
the following format. 



1 byte 



3 bytes 



I Byte } 
K Byte 4 J Flag byte 
i Byte 8 l Error flag 

i i 



J A (label buffer) 
I A (DCB) 

1 

_i 



Figure 58. Parameter List Formats 



The A (label buffer) is the address of 
the label record on input and the address 
where the label will be created on output. 

The A (DCB) is the address of the DCB. 
The DCB contains a pointer to the DEB. The 
nonstandard label SVC routine must test the 
EOF bit in the OFLGS field of the DEB (data 
extent block) to determine whether to 
return control to the EOV or CLOSE module. 
Control is given to the CLOSE module only 
at EOF. 

The error flag byte will have bit set 
to 1 if an input/output error occurs when 
reading or writing a label. 

When the USE BEFORE LABEL PROCEDURE 
section returns control to the nonstandard 
label SVC routine, it will pass a return 
code that will indicate whether or not more 
labels are to be processed (Figure 59). 
This return code is set by assigning a 
value to the special register LABEL- RETURN. 

The maximum size of the label record is 
stored on a halfword boundary at the 
EXITLIST address +46. 



The user*s nonstandard label routines 
are responsible for all tape positioning. 
For multifile volumes, the user may specify 
a file sequence number in the LABEL 
parameter on the DD card. The nonstandard 
label routines can inspect this information 
in the JFCB and position the files 
accordingly. For additional information, 
see the publication OS/VS Tape Labels. 



I ' I 1 1 

I Routine Type JReturn CodeJ Applicable Note! 



j 

Input header J 
and/or \ 4 

trailer | 16 



j_ 

Output header} 
and/or j 
trailer 



Update headerj 8 
and/or I 12 
trailer J 16 



Note s: 

1. For output mode, the label is 
written or rewritten. For input 
mode, normal processing is resumed; 
any additional user labels are 
ignored. 

2. Another label is read (for input 
mode) and control is returned to the 
USE BEFORE LABEL PROCEDURE section. 
For output mode, the labels should 
be written and control should be 
returned to the USE BEFORE LABEL 
PROCEDURE section. When control is 
returned to the nondeclarative 
portion, either normal processing 
will continue or the label section 
will be re-entered, depending on 
whether the return code is 4 or 8. 

3. A return code of 16 indicates that 
the USE BEFORE LABEL PROCEDURE 
section has determined that an 
incorrect volume was mounted. When 
LABEL-RETURN is set to a nonzero 
value, the return code is set to 16. 

i 

Figure 59. Label Routine Return Codes 



ASCII File Labels 



ASCII files on magnetic tape may have 
American National Standard labels or 
American National Standard and user labels, 
or they may have no label. Any labels on 
an ASCII tape must be in ASCII code. Tapes 
containing a combination of ASCII and 
EBCDIC labels are not read. All the record 
formats supported (i-.e.., fixed, undefined, 
and variable) are allowed on ASCII files. 
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regardless of whether or not the files are 
labeled. Spanned records are not supported 
under ASCII. 

When American National Standard labels 
are being processed, the label type must be 
specified in the DD statement that 
describes tbe data set. The parameter for 
American National standard labels is 
LABEL=AL. The parameter for American 
National Standard and user labels is 
LA BE L= AOL. Nonstandard labels are not 
permitted for ASCII files. The user may 
indicate no labels as LABELS=NL. 



files may have user hea 
and user trailer labels 
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possible at the beginni 
file. No check is made 
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der labels (OHLn) 
(UTLn) , which are 

e the standard user 
However, there is 

of user labels 

nq and the end of a 
on the number of 

left to the user to 

Is he wants written. 



All user labels must be 80 bytes in 
length, but they may contain any user 
information desired. 



ASCI I Standard Label Processing 



Mote: USE BEFORE STANDARD LABEL procedures 
are not allowed, because they are 
nonstandard. 



Standard label processing for ASCII 
files is identical to standard label 
processing for files coded in EBCDIC. 
ASCII code is translated into EBCDIC code 
prior to processing. 



User Label Exits 



AgCII lls er Labe l Proc ess in (j 



To create or verify user labels, the 
programmer must code for the file a USE 
AFTER STANDARD LABEL procedure. 



All American National Standard user 
labels (LABEL=AUL) are optional. ASCII 



User Non-VSAM File Processing 159 



I NON-VSAM RECORD FORMATS 



Logical records may be in 
formats for a non-VSAM file: 
(format F) , variable-length 
unspecified (format U) , or s 
S) • F-mode files must conta 
equal lengths. Files contai 
unequal lengths must be v-mo 
S-mode. Files containing lo 
that are longer than physica 
be S-mode. 



one of four 

fixed-length 
(format V) , 
panned (format 
in records of 
ning records of 
de, u~raode, or 
gical records 
1 records must 



The record format is specified in the 
RECORDING MODE clause in the Data Division. 
If this clause is omitted, the compiler 
determines the record format from the 
record descriptions associated with the 
file. If the file is to be blocked, the 
BLOCK CONTAINS clause must be specified in 
the Data Division. 

The prime consideration in the selection 
of a record format is the nature of the 
file itself. The programmer knows the type 
of input his program will receive and the 
type of output it will produce. The 
selection of a record format is based on 
this knowledge as well as aa understanding 
of the type of input/output devices on 
which the file is written and of the access 
method used to read or write the file. 



In unblocked format F, the logical 
record constitutes the block. The BLOCK 
CONTAINS clause is unnecessary for 
unblocked records. 

Format F records are shown in Figure 60. 
The optional control character, represented 
by the letter C in Figure 60 is used for 
stacker selection and carriage control. 
When carriage control or stacker selection 
is desired, the WRITE statement with the 
ADVANCING or POSITIONING option is used to 
write records on the output file, In this 
case, one character position must be 
included as the first character of the 
record (if NOADV is specified) . This 
position will be filled in with the 
carriage control or stacker select 
character. The type of carriage 
control character to be used is 
determined by the compiler. When only 
AFTER is specified, ASA control 
characters are used. Machine control 
characters are used when only BEFORE or 
both BEFORE and AFTER are specified. 
The carriage control character never 
appears when the file is written on 
the printer or punched on the card punch. 



FPEDtLENGTH (FORMAT F) RECORDS 



Format F records are fixed-length 
records. The programmer specifies format F 
records by including RECORDING MODE IS F in 
the file description entry in the Data 
Division. If this clause is omitted and 
both of the following are true: 

• All records in the file are the same 
size 

• BLOCK CONTAINS [ integer- 1 TO J 
integer- 2. .. does not specify 
integer- 2 less than the length of the 
maximum level-01 record 

the compiler determines the recording mode 
to be F. All records in the file are the 
same size if there is only one record 
description associated with the file and it 
contains no OCCURS clause with the 
DEPENDING ON option; or if multiple record 
descriptions are all the same length. 

The number of logical records with! a a 
block (blocking factor) is normally 
constant for every block in the file. When 
fixed-length records are blocked, the 
programmer specifies the BLOCK CONTAINS 
clause in the file description (FD) entry 
in the Data Division. 



I°Ji§.: Illustrations of unblocked Format F 
records do not take into account either the 
key field required when direct organization 
is used or ASCII block prefix 
considerations. See "Processing ASCII 
Files" for more information. 
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Figure 60. Fixed-length (Format F) Records 
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UNSPECIFIED (FORMAT U) RECORDS 



IASIABLE_LENGTH_iFORMAT_VL_EICORDS 



Format U is provided to permit the The pro 

processing of any blocks that do not records by 

conform to F, V, or S formats. Format the file d 

records are shown in Figure 61. The Division, 

optional control character C, as discussed only for d 

under "Fixed-Length {Format F) Records," files. If 

may be used in each logical record. omitted an 

integer-2. 

The programmer specifies format II less than 

records by including RECORDING MODE IS U in compiler d 

the file description (FD) entry in the Data be format 

Division. U-mode records may be specified sequential 

only for direct or physical sequential conditions 
files. 
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If the RECORDING MODE clause is omitted, 
and BLOCK CONTAINS [ integer- 1 TO] 
integer-2... does not specify integer-2 
less than the maximum level-01 record, the 
compiler determines the recording mode to 
be if the file is direct and one of the 
following conditions exist: 

• The FD entry contains two or more 
level-01 descriptions of different 
lengths. 

• A record description contains an OCCURS 
clause with the DEPENDING ON option. 

• A RECORD CONTAINS clause specifies a 
range of record lengths. 



• The FD entry contains two or more 
level-01 descriptions of different 
lengths. 



A record description contains an OCCURS 
clause with the DEPENDING ON option. 



The RECORD CONTAINS clause specifies a 
range of record lengths. 



V-mode records, unlike U-mode or F-mode 
records, are preceded by fields containing 
control information. These control fields 
are illustrated in Figures 62 and 63. 



Each block on the external storage media 
is treated as a logical record. There are 
no record- length or block-length fields. 

Shen a READ INTO statement is used for a 
U-aode file, the size of the longest record 
for that file is used in the MOVE 
statement. All other rules of the MOVE 
statement apply. 

Ngte: Illustrations of Format u records do 
not take into account either the key field 
required when direct organization is used 
or ASCII block prefixes. See "Processing 
ASCII Files" for more information. 



Logical Record 



i — r- 

1 C J 

i 1- 



Data 



Format U Record 
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Figure 61. Unspecified (Format U) Records 



The first four bytes of each block 
contain control information (CC) : 



LL -- represents two bytes designating 

the length of the block (including 
the «cc» field) . 



BB -- represents two bytes reserved for 
system use. 



The first four bytes of each logical 
record contain control information (cc) : 

11 -- represents two bytes designating 
the logical record length 
(including the *cc* field) . 

bb -- represents two bytes reserved for 
system use. 

For unblocked V-mode records (Figure 
62) , the Data portion * CC * cc constitute 
the block. 

For blocked V-mode records (Figure 63) , 
the Data portion of each record ♦ the cc of 
each record ♦ CC constitute the block. 
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Figure 62. Unblocked V-Mode Records 
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When variable-length records are written 
on unit record devices, control bytes are 
neither printed nor punched. They do 
appear, however, on other external storage 
devices. V-mode records moved from an 
input buffer to a working storage area will 
be moved without the control bytes. 



Note: When a READ INTO statement is used 
for a V-mode file, the size of the current 
record for that file is used in the MOVE 
statement. All other rules of the MOVE 
statement apply. For considerations when 
using OCCURS DEPENDING ON, see the section 
"Programming Technigues. " 

l£am£le_J.: 

Consider the following physical 
sequential file consisting of unblocked 
V-mode records: 



FD VARIABLE-FILE- 1 

RECORDING MODE IS V 

BLOCK CONTAINS 35 TO 80 CHARACTERS 
RECORD CONTAINS 27 TO 72 CHARACTERS 
DATA RECORD IS VARI ABLE-RECOSD-1 
LABEL RECORDS ARE STANDARD. 

01 VARIABLE-RECORD- 1. 
LOGICAL RECORD 
05 FIELD-A PIC X (20) . 
05 FIELD-B PIC 99. 
05 FIELD-C OCCURS 1 TO 10 TIMES 

DEPENDING ON 

FIELD-B PIC 9(5) . 



The LABEL RECORDS clause is always 
reguired. The DATA RECORD (S) clause is 
never reguired. If the RECORDING MODE 
clause is omitted, the compiler determines 
the mode as V since the record associated 
with VARIABLE-FILE- 1 varies in length 
depending on the contents of FIELD-B. The 
RECORD CONTAINS clause is never reguired. 
The compiler determines record sizes from 
the record description entries. The BLOCK 
CONTAINS clause is also not reguired, since 
the compiler assumes unblocked records if 
the clause is omitted. Note: Record 
length calculations are affected by the 
following: 



When the BLOCK CONTAINS clause with the 
RECORDS option is used, the compiler 
adds four bytes to the logical record 
length and four more bytes to the block 
length. 



When the BLOCK CONTAINS clause with the 
CHARACTERS option is used, the user 
must include each cc + CC in the length 
calculation. In the definition of 
VARIABLE-FILE- 1, the BLOCK CONTAINS 
clause specifies eight more bytes than 
does the RECORD CONTAINS clause. Four 
of these bytes are the logical record 
control bytes and the other four are 
the block control bytes. 



1st 
Logical Record 



2nd 
Logical Record 



3rd 
Logical Reccrd 

















| LL | EB J 11 J bb J 


DATA-1 


| 11 | bb | 


DATA- 2 


| 11 J bb | 


DATA-3 


1 


l X X- X X 




- X X X 




~L _ X X 







"CC" 

(block control 

bytes) 



'cc 1 

(record control 
bytes) 




L .. J 



Figure 63. Blocked V-Mode Records 
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In Example 1, assume that FIELD-B 
contains the value 2 for the first record 
of a file and FIELD-B contains the value 03 
for the second record of the file. The 
first two records will appear on an 
external storage device and in buffer areas 
of main storage as shown in Figure 6 4. 

If the file described in Example 1 had a 
blocking factor of 2, the first two records 
would appear on an external storage medium 
as shown in Figure 65. 



If VARIABLE-FILE-2 is blocked, with 
space allocated for three records of 
maximum size per block, the following FD 
entry could be used when the file is 
created: 

FD VARIABLE-FILE-2 

RECORDING MODE IS V 

BLOCK CONTAINS 3 RECORDS 

RECORD CONTAINS 20 TO 100 CHARACTERS 

DATA RECORDS ARE VARIABLE-RECORD-1 , 

VARIABLE-RECORD- 2 
LABEL RECORDS ARE STANDARD. 

01 VARIABLE-RECORD-1. 

05 FIELD-A PIC X{20). 
05 FIELD-B PIC X(80) . 

01 VARIABLE-RECORD-2. 

05 FIELD-X PIC X{20). 



As mentioned previously, the RECORDING 
MODE, RECORD CONTAINS, and DATA RECORDS 
clauses are unnecessary. By specifying 
that each block contains three records, the 
programmer allows the compiler to provide 
space for three records of maximum size 
plus additional space for the required 
control bytes. Hence, 316 character 
positions are reserved by the compiler for 
each output buffer. If this size is other 
than that required, the BLOCK CONTAINS 
clause with the CHARACTERS option should be 
specified. If the block size is to be 
specified at execution time by use of the 
BLKSIZE subparameter on an associated DD 
card, BLOCK CONTAINS CHARACTERS must be 
specified. 



Note ; Blocked variable-length records are 
permitted only when the file processing 
technique is physical sequential. 



In Example 2, assume that the first six 
records written are five 100-character 
records followed by one 20-character 
record. The first two blocks of 
VARIABLE-FILE-2 will appear on the external 
storage device as shown in Figure 66. 



1st Block 



2nd Block 



r- T T T T T T T . T T T T T T T T T 1 

| 0040 | BB J 0036 | bb j FIELD-A j 02 | FIELD-C j FIELD-C j 0045 | BB | 041 j bb | FIELD-A j 03 | FIELD-C | FIELD-C | FIELD-C j 
L X X X X X X X X X X L X X X X X J 

Note ; Lengths appear in decimal notation for illustrative purposes. 



Figure 64. Fields in Unblocked V-Hode Records 



1st Record 



2nd Record 



r T T T T T T T T T T T T T " T 1 

| 0081 1 EB 1 0036 | bb | FIELE-A | 02 | FIELD-C | FIELD-C j 0041 1 bb J FIELD-A | 03 ] FIELD-C j FIELD-C J FIELD-C | 
L L J X X X X X X X X X X X X J 



Note : Lengths appear in deciiral notation fcr illustrative purposes. 
Figure 6 5. Fields in Blocked V-Mode Records 



L J 
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1st Block 



2nd Block 



r T T T T T T T T T T T ~— — T T T T T T T r T 1- T -, 

| 316 | BB 1 104 | bb | Data 1 104 | bb| Data 1 104 | bb| Data j * .- | 236 | BB 1 104 | bb | Data 1 104 | bb | Data | 24 | bb | Data | 

L X X X -X J. J. X X X X X-i— X X X X X X X L X__X. L J 

Note : Lengths appear in decimal notation for illustrative purposes. 



Figure 66. First Two Blocks of VARIABLE-FILE-2 
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Note: Illustrations of unblocked Format V 
records do not take into account either the 
key field required when direct organization 
is used or ASCII block prefixes. See the 
description of format D records under 
"Processing ASCII Files". 



APPLY WRITE-ONLY Clause 



The APPLY WRITE-ONLY clause is used to 
make optimum use of buffer space when 
creating a physical sequential file with 
blocked V-mode records. 



t , , , , r % r , 1 — ., ^ 

J 236 j bb | 24 1 bb | Data MO U J bbj Data J 104 1 bb | Data | 

i 1 1 1 J 1 1 i i. c „ i J 



Using the APPLY WRITE-ONLY clause causes 
a buffer to be truncated only when the next 
record does not fit in the buffer. That 
is, if the next three WRITE statements to 
the file specify VARIABLE-RECORD-2, the 
block is created containing six logical 
records, as shown below: 



t , , r — , ., j , , j j 

|308|bbj24|bb| Data]104jbbJ Data J 104|bbfData ' 

i 1 1 a 1 1 1 i 1 %.„ t 



^r 



, J 1 T 1 ! 1 % 1 

24 1 bb | Data! 24 | bb J Data | 24 J bb 1 Data \ 

1 1 1 I I i L J I 



Note: When using the APPLY WRITE-ONLY 
clause, records must not be constructed in 
buffer areas. An intermediate work area 
must be used with a WRITE FROM statement. 



Suppose VARIABLE-FILE-2 is being created 
with the following file description entry: 

FD VARIABLE-FILE- 2 

RECORDING MODE IS V 

BLOCK CONTAINS 316 CHARACTERS 

DATA RECORDS ARE VARIABLE-RECORD-1 , 

VARIABLE- RECORD-2 
LABEL RECORDS ARE STANDARD. 

01 VARIABLE-RECORD-1. 

05 FIELD-A PIC X(20). 
05 FIELD-B PIC X (80) . 

01 VARIABLE-RECORD-2. 

05 FIELD-X PIC X (20). 



The first three WRITE statements to the 
file create one 20-character record 
followed by two 100-character records. 
Without the APPLY WRITE-ONLY clause, the 
buffer is truncated after the third WRITE 
statement is executed since the maximum 
size record no longer fits. The block is 
written as shown below: 



SPANNED {FORMAT S\ RECORDS 



A spanned record is a logical record 
that may be contained in one or more 
physical blocks. Format S records may be 
specified for direct {BDAM, BSAM) files and 
for physical sequential (QSAM) files 
assigned to magnetic tape or to mass 
storage devices. 

When creating files with S-mode records, 
if a record is larger than the remaining 
space in a block, a segment of the record 
is written to fill the block. The 
remainder of the record is stored in the 
next block or blocks, as required. 

When retrieving a file with S-mode 
records, only complete records are made 
available to the user. 

Spanned records are preceded by fields 
containing control information. Figure 67 
illustrates the control fields. 
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BDF (Block Descriptor Field) : 

LL — represents two bytes designating 
the length of the physical block 
(including the block descriptor 
field itself) . 

BB — represents two bytes reserved for 
system use. 



described in the Data Division with the 
following file description entry: 

FD SFILE 

RECORD CONTAINS 250 CHARACTERS 
BLOCK CONTAINS 100 CHARACTERS 



SDF (Segment Descriptor Field) : 

11 — represents two bytes designating 
the length of the record segment 
(including the segment descriptor 
field itself) . 

bb — represents two bytes reserved for 
system use. 

Note: There is only one block descriptor 
field at the beginning of each physical 
block. There is, however, one segment 
descriptor field for each record segment 
within the block. 
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A spanned unblocked file may be 
described as a file composed of physical 
blocks each containing one logical record 
or one segment of a logical record. The 
logical records may be either fixed or 
variable in length. When the physical 
block contains one logical record, the 
length of the block is determined by the 
logical record size. When a logical record 
has to be segmented, the system always 
writes the largest physical block possible. 
The system segments the logical record when 
the entire logical record cannot fit on the 
track. 

Figure 68 is an illustration of blocked 
spanned records of SFILE. SFILE is 
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S-MODE CAPABILITIES 



Formatting a file in the S-mode allows 
the user to make the most efficient use of 
external storage while organizing data 
files with logical record lengths most 
suited to his needs. 

1. Physical record lengths can be 
designated in such a manner as to make 
the most efficient use of track 
capacities on mass storage devices. 

2. The user is not required to adjust 
logical record lengths to maximum 
physical record lengths and their 
device-dependent variants when 
designing his data files. 

3. The user has greater flexibility in 
transferring logical records across 
DASD types. 

Spanned record processing will not be 
supported on unit record devices. 



SEQUENTIAL S-MODE FILES (QSAM) FOR TAPE OR 
MASS STORAGE DEVICES 



When the spanned format is used for QSAM 
files, the logical records may be either 
fixed or variable in length and are 
completely independent of physical record 
length. A logical record may span physical 
records. A physical record may contain one 
or more logical records and/or segments of 
logical records. 



Non/VSAM Record Formats 165 



< — 4 bytes > < — 4 bytes — > < Variable bytes > 




BDF 



SEF 



l j 



Figure 67. Control Fields of an S-Mode Record 
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Figure 68. One Logical Record Spanning Physical Blocks 



Sour ce Language Considerations 



The user specifies s-mode by describing 
the file with the following clauses in the 
file description (FD) entry of his COBOL 
program: 



• BLOCK CONTAINS integer-2 CHARACTERS 

• RECORD CONTAINS [ integer- 1 TO] 
integer-2 CHARACTERS 

• RECORDING MODE IS S 



• Integer-2 is less than the maximum 
length of a variable level-01 FD entry 
(i.e., an entry containing one or more 
OCCURS clauses with the DEPENDING ON 
option) . 

Except for the APPLY WRITE-ONLY, APPLY 
RECORD-OVERFLOW, WRITE BEFORE ADVANCING, 
WRITE AFTER ADVANCING, or WRITE AFTER 
POSITIONING clauses, all the options for a 
variable file apply to a spanned file. 



Proces sin g Se quential S-Mode Files (Q gAM) 



The size of the physical record must be 
specified using the BLOCK CONTAINS clause 
with the CHARACTERS option. Any block size 
may be specified. Block size is 
independent of logical record size. 

The size of the logical record may be 
specified by the RECORD CONTAINS clause. 
If this clause is omitted, the compiler 
will determine the maximum record size from 
the record descriptions under the FD. 

Format S may be specified by the 
RECORDING HODE IS S clause. If this clause 
is omitted, the compiler will set the 
recording mode to S if the BLOCK CONTAINS 
inteter-2 CHARACTERS clause was specified 
and either of the following conditions 
exist: 

* Integer-2 is less than the largest 
fixed- length level-01 FD entry. 



Suppose a file has the following file 
description entry: 

FD SPAN-FILE 

BLOCK CONTAINS 100 CHARACTERS 
LABEL RECORDS ARE STANDARD 
DATA RECORD IS DATAREC. 

01 DATAREC. 

05 FIELD-A PIC X (100). 
05 FIELD-B PIC X (50). 

Figure 69 illustrates the first four 
blocks of SPAN-FILE as they would appear on 
external storage devices (i.e., tape or 
mass storage) or in buffer areas of main 
storage. 

Notes: 

1. The RECORDING HODE clause is not 

specified. The compiler determines 
the recording mode to be S since the 
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block size is less than the record 
size. 



The length of each physical block is 
100 bytes, as specified in the BLOCK 
CONTAINS clause. All required control 
fields, as well as data, must be 
contained within these 100 bytes. 

No provision is made for the control 
fields within the level-01 entry 
DATAREC. 
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One advangage of s-mode records over 
V-mode records is illustrated by a file 
with the following characteristics: 

1. RECORD CONTAINS 50 TO 150 CHARACTERS 

2. BLOCK CONTAINS 350 CHARACTERS 

3. The first five records written are 
150, 150, 150, 100, and 150 characters 
in length. 

For V-raode records, buffers are 
truncated if the next logical record is too 
large to be completely contained in the 
block (Figure 70). This results in more 
physical blocks and more inter-record gaps 
on the external storage device. 

Note: For V-mode records, buffer 
truncation occurs: 

1. When the maximum level-01 record is 
too large. 



4 4 

<-bytes-X-bytes-X- 



92 
-bytes- 



r T T - T T 




ILL |BB |11 | bb | 


DATAREC ( 1 ) 


L X X X J 





4 4 58 a 30 
> <-bytes-X-bytes->< bytes ><-bytes-><- -bytes > 

1 r T T T T T T T T 

| |LL |BB |11 | bb | DATAREC (1) | 11 | bb | DATAREC (2)| 



U X X X X 



X L X 



1st Block 



2nd Block 



4 4 
<-bytes-X-bytes-X- 



92 
-bytes- 



r T T T T 




ILL |BB |11 | bb | 


DATAREC (2) 


L X XXX. 





3rd Block 

L 



4 4 28 4 bO 
> <-bytes-X-bytes->< — bytes X-bytes-X oytes > 

T r T T T T T T T 1 

| |LL |BB jll | bb | DATAREC (2)|11 | bb | DATAREC (3) | 

J L X X X X X J X J 

4th Block 

j 



Figure 69. First Four Blocks of SPAN-FILE 



r 




T ~ " 




1 


RECORDING MODE IS V 


] 


RECORDING MODE IS S 


L 




+ 





r t 1 r t n r 1 

| 150 j 150 ] G j 150 1 100 | G | 150 | 
l 4. J L X J L J 



r t r 1 r t t 1 

I 150 j 150 j 50 j G j 100 | 100 | 150 j 

L X X J I X X J 



Rl 



R2 



R3 



RU 



R5 



Rl 



R2 



R3 



R4 



R5 



y X 

Note : The enclosed diagrairs are for illustrative purposes only. Neither takes into 
account the space required for control fields.. 

i J 

Figure 70. Advantage of S-Mode Records Over V-Mode Records 
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2. If APPLY WRITE-ONLY or SAME RECORD 
AREA is specified and the actual 
logical record is too large to fit 
into the remainder of the buffer. 

For s-mode records, all blocks are 350 
bytes in length and records that are too 
large to fit entirely into a block will be 
segmented, This results in more efficient 
use of external storage devices since the 
number of inter-record gaps are minimized 
{Figure 70). 

A second advangage of s-aode processing 
over that of V-raode is that the user is no 
longer limited to a record length that does 
not exceed the track of the mass storage 
device selected. Records may span tracks, 
cylinders, extents, and volumes. 
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The allocation of a Logical Record Area 
may be a disadvantage to the COBOL user. 
Additional main storage, consisting of 36 
bytes + the maximum record length, will 
always be reguired. The Logical Record 
Area is discussed in detail in "Finding 



Data Records in an Abnormal Termination 
Dump." 



DIRECTLY ORGANIZED S-MODE FILES (BDAM AND 
BSAM) 



When S-mode is used for directly 
organized files, only unblocked records are 
permitted. Logical records may be either 
fixed or variable in length. A logical 
record will span physical records if, and 
only if, it spans tracks. A physical 
record will contain only one logical record 
or a segment of a logical record. A track 
may contain a segment of a logical record, 
or segments of two logical records and/or 
whole logical records. Records may span 
tracks, cylinders, and extents, but not 
volumes. 



Source Language Considerations 



The user specifies S-mode by describing 
the file with the following clauses in the 
file description (FD) entry of his COBOL 
program: 

• BLOCK CONTAINS integer-2 CHARACTERS 

• RECORD CONTAINS [integer-1 TO] 
integer-2 CHARACTERS 

• RECORDING MODE IS S 

The size of a logical record may be 
specified by the RECORD CONTAINS clause. 
If this clause is omitted, the compiler 
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Figure 71. Direct and Sequential Spanned Files on a Mass Storage Device 
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will determine the maximum record size from 
the record descriptions under the FD. 



Processing Dir ectly Organized S -M pde Files 
(BDAM and BSAM) 
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When processing directly organized 
files, there are two advantages spanned 
format has over the other record formats: 



The physical block size is determined by 
either: 



1. The logical record length. 



2. The track capacity of the device being 
used. 
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mass storage device 
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logical record is gr 
characters, the reco 
first segment may be 
physical block of up 
remaining segments m 
succeeding blocks, 
logical record will 
if, and only if, it 



the track capacity of a 
is 7294 characters, any 
7294 characters may be 
physical block. If a 
eater than 7294 
rd is segmented. The 

contained in a 

to 7294 bytes, and the 
ust be contained in 
In other words, a 
span physical blocks 
spans tracks. 



Figure 71 illustrates four 
variable-length records <R1, R2, E3, and 
R4) as they would appear in direct and 
sequential files on a mass storage device. 
In both cases, control fields have been 
omitted for illustrative purposes. For 
both files, assume: 

1. BLOCK CONTAINS 7294 CHARACTERS (track 
capacity = 7294) 

2. RECORD CONTAINS 500 TO 8000 CHARACTERS 



In the sequential file, each physical 
block is 7294 bytes in length and is 
completely filled with logical records. 
The file consists of three physical blocks, 
occupies three tracks, and contains no 
inter-record gaps. 

In the direct file, the physical blocks 
vary in length. Each block contains only 
one logical record or one record segment. 
Logical record R3 spans physical blocks 
only because it spans tracks. The file 
consists of seven physical blocks, occupies 
more than three tracks, and contains three 
inter-record gaps. 
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Logical record lengths may exceed the 
length restriction of the track 
capacity of the mass storage device. 
If, for example, the track capacity of 
a mass storage device is 2000 bytes, 
this does not represent the maximum 
length of the logical record that can 
be specified (even when the device 
does not have a Track overflow 
feature) . 

Note: Even when the spanned format is 
used, the COBOL restriction on the 
length of logical records must be 
adhered to (i.e., a maximum length of 
32,767 characters). 
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!2ti~: If a choice exists between 
Track Overflow and S-mode records, 
neither has any particular advantage 
over the other with regard to the 
efficient use of storage space. 

The disadvantage of BSAM and BDAM 
spanned records is similar to that 
mentioned for QSAM. A segment work area is 
always allocated which occupies additional 
main storage. 

Like QSAM, the processing of BSAM and 
BDAM spanned records relies on an 
interaction between buffers, segment work 
areas, and Logical Record Areas. For QSAM, 
input-output buffers are used as the 
segment work area and complete logical 
records are assembled in a Logical Record 
Area before being made available to the 
user if the record is segmented. If the 
record is not segmented, the logical 
recordis made available to the user within 
the buffer unless the SAME AREA clause is 
specified. For BSAM and BDAM, input-output 
buffers are used as a Logical Record Area 
and a separate segment work area must be 
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allocated. Segment work areas and Logical 
Record Areas are described fully in 
"Finding Data Records in an Abnormal 
Termination Dump." 

OCCD RS ,, CL AUS E WITH T HE DEPENDING ON OPTION 

If a record description contains an 
OCCURS clause with the DEPENDING ON 
option, the record length is variable. This 
is true for records described in an FD as 
well as in the Working-Storage section. 
The previous sections discussed four 
different record formats. Three of them, 
V-mode, U-mode, and s-mode, may contain one 
or more OCCURS clauses with the DEPENDING 
ON option. 

The following section discusses some 
factors that affect the manipulation of 
records containing OCCURS clauses with the 
DEPENDING ON option. The text indicates 
whether the factors apply to the File (FD) 
or Working-Storage sections, or both. 

The compiler calculates the length of 
records containing an OCCURS clause with 
the DEPENDING ON option at two different 
times, as follows (the first applies to FD 
entries only, the second to both FD and 
Working-Storage entries) : 

1. When a file is read and the object of 
a DEPENDING ON option is within the 
record. 

2. When the object of the DEPENDING ON 
option is changed as a result of a 
move to it or to a group that contains 
it. (The length is not calculated 
when a move is done to an item which 
redefines or renames it.) 

Consider the following example: 
WOBKING-STORAGE SECTION. 



77 
77 



CONTROL- 1 
WORKAEEA-1 



PIC 99. 

PIC 9(6) V99. 



01 SALARY-HISTORY. 

05 SALARY OCCURS 1 TO 1 TIMES 
DEPENDING 
ON CONTSOL-1 PIC 9(6) V99. 

The Procedure Division statement MOVE 5 
TO CONTROL- 1 will cause a recalculation of 
the length Of SALARY-HISTORY- MOVE SALARY 
(5) TO WORKAREA-1 will not cause the length 
to be recalculated. 

The compiler permits the occurrence of 
more than one level-01 record, containing 
the OCCURS clause with the DEPENDING ON 
option, in the same FD entry (Figure 72) . 
If the BLOCK CONTAINS clause is omitted, 



the buffer size is calculated from the 
longest level-01 record description entry. 
In Figure 72, the buffer size is determined 
by the description of RECORD- 1 (RECORD- 1 
need not be the first record description 
under the FD) . 

During the execution of a READ 
statement, the length of each level-01 
record description entry in the FD will be 
calculated (Figure 72). The length of the 
variable portions of each record will be 
the product of the numeric value contained 
in the object of the DEPENDING ON option 
and the length of the subject of the OCCURS 
clause. In Figure 72, the length of 
FIELD- 1 is calculated by multiplying the 
contents of CONTROL- 1 by the length of 
FIELD- 1; the length of FIELD-2, by the 
product of the contents of CONTROL-2 and 
the length of FIELD-2; the length of 
FIELD- 3 by the contents of CONTROL-3 and 
the length of FIELD-3. 

Since the execution of a READ statement 
makes available only one record type (i.e., 
RECORD-1 type, RECORD-2 type, or RECORD-3 
type), two of the three record descriptions 
in Figure 72 will be inappropriate. In 
such cases, if the contents of the object 
of the DEPENDING ON option does not conform 
to its picture, the length of the 
corresponding record will not be 
calculated. For the contents of an item to 
conform to its picture: 



An item described as USAGE DISPLAY 
contain decimal data. 



mst 



• An item described as USAGE 
COMPUTATIONAL- 3 must contain internal 
decimal data. 

• An item described as USAGE 
COMPUTATIONAL must contain binary data. 

• An item described as USAGE DISPLAY 

or USAGE COMPUTATIONAL-3 must conform 
to the rules for the numeric class 
test condition: 

If the PICTURE for the item does 
not contain an operational sign, 
the item being tested conforms 
only if the contents are unsigned 
numeric . 

- If the PICTURE clause for the 

item does contain an operational 
sign, the identifier being 
tested conforms only if the item 
is elementary signed numeric. 

In the EBCDIC collating sequence for 
signed items, valid embedded opera- 
tional signs are hexadecimal C, D, 
and E; for items described with the 
SIGN IS SEPARATE clause, valid 
operational signs are + (hexadecimal 
4E) and - (hexadecimal 6 0) . 
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FD INPUT-FILE 



DATA BECORDS ARE fiECORD-1 RECORD-2 RECORD-3. 

01 RECORD-1. 

02 CONTRQL-1 PIC 99. 

02 FIELD-1 OCCURS 1 TO 10 TIMES DEPENDING ON CONTROL-1 PIC 9(5). 

01 RECORD-2. 

02 CONTROL-2 PIC 99. 

02 FIELD- 2 OCCURS 1 TO 5 TIMES DEPENDING ON CONTROL-2 PIC 9(4). 

01 RECORD-3. 

02 FILLER PIC XX. 

02 CONTROL-3 PIC 99. 

02 FIELD-3 OCCURS 1 TO 10 TIMES DEPENDING ON CONTROL-3 PIC X (4) . 

t J 

Figure 72. Calculating Record Lengths When Using the OCCURS Clause with the DEPENDING ON 
Option 



The following example illustrates the 
length calculations made by the system when 
a READ statement is executed: 



FD 



3. The length of TABLE- 3 is calculated 
using the contents of field B. 

4. The length of TABLE-U is calculated 
using the contents of field E. 



01 RECORD-1. 

05 A PIC 99. 
05 B PIC 99. 

05 C PIC 99 OCCURS 1 TO 5 TIMES 
DEPENDING ON A. 

01 RECORD-2. 

05 D PIC XX. 
05 E PIC 99. 
05 F PIC 99. 

05 G PIC 99 OCCURS 1 TO 5 TIMES 
DEPENDING ON F. 



The user should be aware of several 
additional factors that affect the 
successful manipulation of variable-length 
records. The following example illustrates 
a group item (i.e., REC-1) whose 
subordinate items contain an OCCURS clause 
with the DEPENDING ON option and the object 
of that DEPENDING ON option. 

WORKING-STORAGE SECTION. 
01 REC-1. 

05 FIELD-1 PIC S9. 

05 FIELD-2 OCCURS 1 TO 5 TIMES 

DEPENDING ON FIELD-1 PIC X (5) . 



WORKING-STORAGE SECTION. 



01 REC-2. 

05 REC-2-DATA 



PIC X(50) 



01 TABLE-3. 

05 H OCCURS 1 TO 10 TIMES DEPENDING 
ON B. 



01 TABLE-4. 

05 I OCCURS 1 TO 10 TIMES DEPENDING 
ON E. 

When a record is read, lengths are 
determined as follows; 

1. The length of RECORD-1 is calculated 
using the contents of field A. 

2. The length of RECORD-2 is calculated 
using the contents of field F. 



The results of executing a MOVE to the 
group item REC-1 will be affected by the 
following: 

* The length of REC-1 may have been 
calculated at some time prior to the 
execution of this MOVE statement. The 
user should be sure that the current 
length of REC-1 is the desired one. 

* The length of REC-1 may never have been 
calculated at all. In this case, the 
result of the tove will be 
unpredictable. 

* After the move, since the contents of 
FIELD-1 have been changed, an attempt 
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will be made to recalculate the length 
of REC-1. This recalculation, however, 
will be Bade only if the ne» contents 
of FIELD- 1 conform to its picture. In 
other words, if FIELD- 1 does not 
contain an external decimal item, the 
length of EEC-1 will not be 
recalculated. 



Assune that CONTROL- 1 contains the value 
5 and VARY-FIELD- 1 contains 5 entries. 



In order to add a sixth field to 
7ARY-FIELD-1, the following steps are 
required; 
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The following example applies to 
updating a record containing an OCCURS 
clause with the DEPENDING ON option and at 
least one other subsequent entry. In this 
case, the subsequent entry is another 
OCCURS clause with the DEPENDING ON option. 

WORKING-STORAGE SECTION. 
01 VARIABLE-REC. 

05 FIELD-A PIC X(10) . 

05 CONTROL- 1 PIC S99. 

05 CONT80L-2 PIC S99. 

05 VARY-FIELD- 1 OCCURS 1 TO 1 TIMES 

DEPENDING ON CONTROL- 1 PIC X(5) . 
05 GROUP- ITEM- 1 . 

10 VARY-FIELD- 2 OCCURS 1 TO 1 
TIMES DEPENDING ON CONTROL- 2 
PIC X(9) . 
01 STORE -VARY- FIELD- 2. 
03 GROUP -ITEM- 2. 

05 VARY-FLD-2 OCCURS 1 TO 1 

TIMES DEPENDING ON CONTROL- 2 
PIC X(9) . 



MOVE GROUP- ITEM- 1 TO GROUP- ITEM- 2 . 
ADD 1 TO CONTROL- 1. 
MOVE *additional field* TO 
VARY-FIELD- 1 (CONTROL-1). 
MOVE GROUP- ITEM- 2 TO GROUP-ITEM-1 . 

Note ; When an FD contains multiple 
01 -level entries, the following restriction 
applies: The object of an OCCURS 
DEPENDING ON clause must be in the 
fixed portion of all the records within 
that FD (not just in the fixed portion of 
the record it is described in) . Stated 
another way, the minimum size of each 
01 -level record must exceed the highest 
position of the object of an OCCURS 
DEPENDING ON clause appearing in any 
01 -level record in that FD. Thus, the 
following coding would be wrong , and could 
cause an abend: 

FD 

01 RECORD- 1. 

02 FIELDA PIC X(200) . 
02 FIELDB PIC 99. 

02 FIELDC PIC XX OCCURS 1 TO 25 TIMES 
DEPENDING ON FIELDB. 
01 RECORD- 2. 

02 FIELDD PIC X(100). 

For a discussion of the use of the 
OCCURS DEPENDING ON clause in a sort 
program, see "Sorting Variable-Length 
Records. " 



172 



VSAM FILE PROCESSING 



VSAM is a high-performance access method 
of OS/VS for use with direct-access 
storage- VSAM provides high-speed 
retrieval and storage of data, ease of use 
{including simplified JCL statements) , data 
protection against unauthorized access, 
central control of data management 
functions, cross-system compatibility, and 
device independence. VSAM data sets can be 
processed by the COBOL programmer after 
they have been defined through use of the 
VSAM multifunction utility program known as 
Access Method Services. This utility 
(described in the publications OS/VS 1 
Access Met hod Serv ices and OS/VS 2 Access 
Method Ser vice s) will describe data sets, 
load records into them if desired, and 
perform numerous other tasks — such as 
converting existing ISAM and SAM data sets 
to VSAM format. 



TYPES OF VSAM DATA SETS 



slot, new records are inserted either 
seguentially in the next available slot, 
where they assume that relative record 
number, or according to a relative record 
number that the programmer specifies. 
Records may be retrieved either 
sequentially or by specific relative record 
number. 



EHTRY-SEQOEHCED DATA SETS 



An entry-seguenced data set has no index 
associated with it. Records are added at 
the end of the data set. The data set can 
be accessed sequentially only; the access 
is similar to QSAM except that tape storage 
or unit record devices cannot be used with 
VSAM. 



COBOL allows access to the three major 
types of VSAM data sets: entry-seguenced 
(ESDS) , key-sequenced (KSDS) and relative 
record (ERDS). The primary difference 
between the three is the order in which 
their data records are stored and 
retrieved. 
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Records are stored in a relative record 
data set in relative record number 
sequence. The data set may be described as 
a string of fixed-length slots, each of 
which is identified by a number which gives 
its position relative to the first such 



KEY-SEQOENCED DATA SETS 



The index and distributed free space are 
the most distinctive features of a 
key-sequenced data set. 

The index relates key values to the data 
records in the data set. A record's key 
field and position are the same for every 
record in the data set; its value cannot be 
altered. VSAM uses the index to locate a 
record for retrieval and to locate the 
collating position for insertion. 
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When a key-sequenced data set is defined 
{through Access Method Services) , free 
space can be distributed in two ways: by 
leaving some space at the end of all the 
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used control intervals 1 and by leaving some 
control intervals completely empty. Space 
becomes available within a control interval 
when a record is shortened or deleted. 
This space can then be used by VSAM when a 
record is lengthened in place or inserted 
into the control interval. 



and EXPORT commands provide a way to 
transfer data sets from one system to 
another. The BLDINDEX command builds 
alternate indexes for VSAM KSDS data sets. 
The VERIFY command provides a data set 
recovery service for VSAM data sets by 
verifying that the end of the data set 
indicated in the catalog is the same as the 
real data set end. 



RELATIVE RECORD DATA SETS 



A relative record data set has no index. 
In its string of fixed-length slots, only 
the relative record number — a number from 1 
to n, where n is the maximum number of 
records that can be stored in the data 
set — identifies the record. Each record 
occupies one slot, and is stored and 
retrieved according to the relative record 
number of that slot. The record's contents 
and entry seguence are unimportant. 

Records in a relative record data set 
are grouped together in control intervals, 
just as they are in a entry-seguenced or 
key-seguenced data set. Each control 
interval contains the same number of slots. 
The size of each slot is the record length 
specified by the user when he defined the 
data set. 



ACCESS METHOD SERVICES 
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There are a number of important 
functional commands: DEFINE, ALTER, 
DELETE, LISTCAT, REPRO, PRINT, IMPORT, 
EXPORT, BLDINDEX, and VERIFY. The commands 
DEFINE, ALTER, DELETE, and LISTCAT are used 
to create, modify, remove and list entries 
in the VSAM catalog. The REPRO and PRINT 
commands reproduce data sets either as new 
data sets or as printed output. The IMPORT 



THE DEFINE COMMAND 



The DEFINE command must be used to 
define: 



1. 
2. 
3. 

4. 
5. 



Master catalog: catalog in which all 
VSAM data sets must be entered. 

User catalog: optional catalog in 
which VSAM data sets may be entered. 



Data space: 
by VSAM. 



space which is to be used 



VSAM data set (s) : data sets that are 
to be processed by VSAM. 

Any alternate indexes and alternate 
paths. 



* A control interval is the unit of 
information that VSAM transfers between 
virtual and auxiliary storage. 



In order to process a VSAM data set, the 
above must be done in the order indicated. 
Therefore it is necessary to fully 
understand the DEFINE command, its 
functions, and its specification. 



Functions o f the DEFI NE Command 

An object, in VSAM terminology, is: 

• A VSAM catalog 

• A VSAM data set (KSDS, RRDS, or ESDS) 

• A VSAM data space 

• A VSAM KSDS alternate index and path 

Data sets must be introduced to the 
system and defined as entries in either the 
master or user catalog. Non-VSAM data sets 
may also be cataloged in a VSAM catalog. 
All VSAM and non-VSAM data sets are 
introduced to the system with the DEFINE 
command. 

There are two steps in the creation of 
an object: (1) defining the object to the 
system and (2) generating its contents. 
The DEFINE command does not generate the 
contents of any object except for the 
entries in the master and user catalogs. 
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The process of defining a VSAM object 
includes allocation of storage space, 
initialization of catalog entry contents, 
and, in the case of defining catalogs, 
possible initialization of the object* s 
storage space- 



Spe cification of the DEFINE Com mand 



the data space automatically created are 
placed in the master catalog. 

The following is an example of defining 
a VSAM master catalog: 



//MYJ0B1 
//STEP 
//SY SPRINT 
//VOL 



JOB 
EXEC 
DD 
DD 



PGM=IDCAMS 
SYSOUT=A 

DISP=OLD,UNIT=2314, 
VOL=SER=MYVOL 



The DEFINE command has the following 
format: 

DEFINE object parameters 

The definable objects are as follows: 

• MASTERCATALOG: specifies that the 
VSAM master catalog is to be defined. 

• USERCATALOG: specifies that a VSAM 
user catalog is to be defined. 

• SPACE: specifies that a VSAM data 
space is to be defined. 

• CLUSTER: specifies that a data set is 
to be defined. 

• ALTER NATEINDEX: specifies that an 
alternate index for a KSDS is to be 
defined and have space allocated. 

• PATH: establishes the relationship 
between an alternate index and its 
data set (base cluster) . 

• NONVSAM: specifies that a data set 
not having the VSAM data set 
organization is to be cataloged in a 
VSAM catalog. 

For each data set there is an associated 
valid parameter list. See the publication 
OS/ VS A ccess Method, Services for the 
specification rules for DEFINE and its 
associated objects and parameters. 



De fining , a Master Ca talog; DEFINE 

MASTERCATALOG 



The DEFINE MASTERCATALOG command is used 
in VS1 to set up the master catalog. (In 
VS2, this command only creates a user 
catalog. The VS2 master catalog is created 
at system-generation time.) It is the first 
Access Method Services command ever used 
since without a master catalog other 
objects cannot be defined. Defining a 
master catalog automatically creates the 
data space necessary to contain the 
catalog. Entries for both the master 
catalog itself and the volume containing 



//SYSIN 



DD 



DEFINE MASTERCATALOG (NAME 

(MASTCATL) FILE (VOL) 
VOLUME(myvol) RECORDS 
(300 10) + 
MASTERPH(111111) f 
UPDATEPH (222222) + 
READPW (333333) ) 



/+ 



Note the following concerning the JCL 
used. 

• PGM=IDCAMS is required to invoke Access 
Method Services. 

• MYVOL is the volume serial number of 
the volume on which the master catalog 
is to reside. //VOL is the DD 
statement identifying that volume. 

In this example the following parameters 
were used: 

• NAME (objectname) . This is a required 
parameter. The objectname is cataloged 
and is the name that must be used in 
all future references to the master 
catalog. 

• FILE (dname) . This is a required 
parameter identifying the JCL statement 
that specifies the device and volume 
which are to contain the master 
catalog. The associated JCL statement 
should specify DISP=0LD. For dname, 
the name of the JCL statement that 
specifies the device and volume to 
contain the master catalog is 
substituted. 

• VOLUME (volser) . This is a required 
parameter that specifies the volume to 
contain the master catalog. 

• RECORDS <primary[ secondary]). This is 
a required parameter that specifies the 
amount of space to be allocated in 
terms of the number of records the 
space is to hold. The capacity of the 
allocated space is device independent. 
The size of the primary extent is 
specified by primary. Once the primary 
extent is filled, the data space can 
expand to include a maximum of 15 
secondary extents if the size of 
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secondary extents is specified through 
secondary. 
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UPDATEPW (password). This optional 
parameter specifies an update level 
password. The password permits read 
and write operations against the master 
catalog. The master catalog must be 
password protected if any VSAM clusters 
are to be protected. 

READPK (password). This optional 
parameter specifies a read level 
password for the master catalog being 
defined. The read level password 
permits read operations against the 
master catalog. The master catalog 
must be password protected if any VSAM 
clusters are to be protected. 



Defining a User C ata log; DEFINE 

USMCATALOG 



The DEFINE USEECATALOG command is used 
to set up user catalogs. When a user 
catalog is defined, a data space to 
containthe catalog is automatically 
created. An entry for the volume 
containing the data space is placed in the 
user catalog being defined. Entries for 
the user catalog being defined are placed 
in the master catalog and in the user 
catalog itself. 

The parameters that may be used with 
DEFINE USESCATALOG are the same as those 
described for DEFINE MASTERCATALGG with one 
exception. There is an additional 
parameter that may be used with DEFINE 
OSESCATAIOG as follows: 



CATALOG (aastercatname/password) . This 
parameter specifies the name and 
password of the master catalog that 
contains the entry for the user catalog 
being defined. This parameter is 
reguired only when the master catalog 
is password protected. 

For mastercatname, the name of the 
master catalog is substituted. For 
password, the update or higher level 
password is substituted. 



Defining a VSAM Data Sp ace: 



►ACE 



The DEFINE SPACE command is used to 
define VSAM data spaces or to reserve 
volumes for future use by VSAM. A VSAM 
data space is space on a direct access 
volume that is owned and managed by VSAM. 
Clusters cannot be defined without the 
UNIQUE attribute unless a VSAM data space 
is defined to contain them. A VSAM data 
space may include several extents on the 
same volume but it cannot span volumes. 
The volume containing the data space is 
owned by the catalog containing the entry 
for the space. Data spaces on several 
volumes can be defined at one time. 

The following is an example of defining 
a VSAM data space: 



//MYJ0B2 
//STEP 
//SY SPRINT 
//SP ACDD 



//SYSIN 



JOB 
EXEC 
DD 
DD 

DD 



PGM=IDCAMS 

SYSOUT=A 

DISP=0LD,UNIT=2314, 

VGL=SER=MYVOL 

* 

DEFINE SPACE (VOLUME (MY VOL) FILE + 
(SPACDD) + 

CYLINDERS (30 5) CATALOG* 
(MASTCATL/222222) 



In this example the following parameters 
were used: 

* VOLUMES (volser[ ...]). This required 
parameter specifies the volumes to 
contain the data spaces. If more than 
one volume is specified, each volume 
will contain a data space of the same 
size. 

• FILE(dname). This required parameter 
identifies the JCL statement that 
specifies the devices and volumes to be 
used for space allocation. [For dname, 
substitute the name of the JCL 
statement that specifies the devices 
and volumes to be used for space 
allocation. ] All volumes must be of the 
same device type. 
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• CYLINDERS {primary[ secondary ]) . This 
parameter specifies the amount of space 
to be allocated in terms of cylinders. 
The capacity of the allocated space is 
device dependent. Either this 
parameter or the TRACKS or RECORDS 
parameter must be specified. The size 
of the primary extent is specified by 
primary. Once the primary extent is 
filled, the data space can expand to 
include a maximum of 15 secondary 
extents if the size of secondary 
extents is specified through secondary. 
For primary and secondary, the number 
of cylinders to be allocated to the 
data space is substituted. 



CATALOG (catname{ /password ][ dname ]} . 
This parameter specifies the name and 
password of the catalog in which the 
data space is to be defined. [ For 
catname, substitute the name of the 
catalog that is to contain the entry 
for the data space. ] This parameter is 
specified if the desired catalog is not 
the default catalog (see Defaults 
below) . If the catalog is password 
protected, the password must be 
specified. 



If the desired catalog is neither the 
master catalog nor a catalog identified 
by a JOBCAT or STEPCAT DD statement, 
the name of the DD statement 
identifying the catalog must be 
specified. For dname, the name of the 
DD statement that identifies the 
desired catalog is substituted. 



Defaults : The data space is defined in 
the catalog identified as STEPCAT. If 
STEPCAT is not provided, the data space 
is defined in the catalog identified as 
JOBCAT. If JOBCAT is not provided, the 
data space is defined in the master 
catalog. 



Defining a KSDS 



Figure 73 is an example of defining an 
indexed VSAM data set. DEFINE CLUSTER is 
used to define the attributes of all VSAM 
data sets and to catalog the data sets in < 
VSAM catalog. This command does not put 
any records into the VSAM data set. COBOL 
permits reference only to a KSDS cluster; 
in other words, the KSDS's data and index 
components cannot be defined separately. 



The DEFINE CLUSTER command establishes 
the primary keys for the records. If only 
primary keys are to be used, then only this 
DEFINE CLUSTER command is needed. If 
alternate keys are also to be used (as in 
this example) , they are established with 
the DEFINE ALTERNATEINDEX ana DEFINE PATH 
commands. In addition (after the base 
cluster is filled with records) , a 
follow-on job must be run to specify the 
BLDINDEX command (see the Access Method 
Services manual) . 

In this example the following parameters 
were used: 

• NAME (objectname) . This is a required 
parameter. It must be specified at the 
cluster level. 

• FILE identifies the DD statement 
specifying the device and volume that 
are to contain the VSAM object being 
defined. 

• VOLUME (volser [ ...]). This is a 
required parameter that specifies the 
volumes to contain the object. More 
than one volume can be specified; the 
volumes actually allocated are listed. 

• RECORDS (primary [ secondary]) specifies 
the amount of space to be allocated in 
terms of the number of records the 
space is to hold. 
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//MXJ0B3 


JOB 


//STEP 


EXEC 


//SYSPRINT 


DD 


//MYDD 


DD 


//SYSTN 


DD 


DEFINE 





DEFINE 



DEFINE 



PGM=IDCAMS 

SYSOUT=A 

VOL=SER=MYVOL,UNIT=SYSDA,DISP=OLD 

* 

CLUSTER (NAME (SAMPLE) FILE (MYDD) VOLUME (MYVOL) 
RECORDS (500 50) RECORDSIZE (45 80) ♦ 

FREESPACE(25 10) SUBALLOCATION INDEXED ♦ 
KEYS (8 2) UPDATEPW(RDANDWRT) READPW (READONLY) 
ATTEMPTS (0)) , CATALOG (M ASTCATL/222 222) 
ALTERNATEINDEX(NAME(ALTX) RELATE (SAMPLE) 
FILE(MYDDI) VOLUME (MY VOL) RECORDS (500 
KEYS (6 15) UNIQUEKEY UPDATEPW (HD ANDWRT) 
ATTEMPTS (0)) CATALOG ( M ASTCATL/2 22 222) 
PATH (NAME(PATHX) PATHENTRY(ALTX) UPDATE 
CATALOG (MASTCATL/222 222) 



50) 



+ 



READPW(READONLY)-f 
UPGRADE 



I 



Figure 73. Defining a VSAM Indexed Data Set (KSDS) with Both Primary and Alternate Keys 



* RECORDSIZE (average maximum) specifies 
the average and maximum lengths of the 
records in the data component of the 
cluster. This is a required parameter. 
The size specified can be from 1 to 
32,761. 



The number substituted for average 
should be the number of bytes that is 
the average length of all logical 
records. The number substituted for 
maximum should be the maximum length of 
the largest logical record. 

• FREESPACE(cipercent[ capercent]) 
specifies the amount of space that is 
to be left free after any allocation 
and after any split of control 
intervals and control areas. The 
amount is specified as a percentage. 

For cipercent, the percentage of unused 
space desired in each control interval 
is specified. For capercent, the 
percentage of unused space desired in 
each control area is specified. 

• SUBALLOCATION specifies that a portion 
of an already defined VSAM data space 
is to be suballocated to the object. 
Objects with the SUBALLOCATION 
attribute do not appear in the VTOC. 
Only the name of the data space that 
contains the object appears there. 

• INDEXED specifies that the cluster 
being defined is for a KSDS. 

• KEYS (length position) specifies the 
length of the keys in a KSDS and their 
position within the records. The 
length of the keys is specified by 
length; the displacement of the keys 
within the record is specified by 



position. The first character in a 
record is at displacement 0. 

UPDATEPW (password) specifies an update 
level password for the data set being 
defined. The update level password 
permits input and update (READ, START, 
DELETE, WRITE, REWRITE) operations 
against the logical records of the data 
set. 

8EADPW (password) specifies a read level 
password for the object being defined. 
The read level password permits input 
(READ, START) operations against the 
logical records of the data set. 

ATTEMPTS (number) specifies the maximum 
number of times the operator can try to 
enter a correct password in response to 
a prompting message. This parameter 
should always specify as the number. 

CATALOG (catna me£ /password ][ dnamej) 
specifies the name of the catalog into 
which the cluster is to be defined. 
The name of the catalog is substituted 
for catname. if the catalog is 
password protected, the password must 
also be supplied. 

The name of the DD statement 
identifying the catalog must be 
specified if the catalog is neither the 
master catalog nor a catalog identified 
by a JOBCAT or STEPCAT DD statement or 
if the catalog obtained through the 
default is not the desired catalog. 
For dname, substitute the name of the 
DD statement that identifies the 
catalog. 

RELATE specifies the name of the base 
cluster, as given in the (NAME (name) ) 
field of the DEFINE CLUSTER for this 
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data set. This is a required 
parameter. 

• UNIQUEKEY/NONUNIQUEKEY specifies 
whether each alternate key points to 
only one data record or to more than 
one. If to more than one, then 
NONUNIQUEKEY must be specified and the 
COBOL program must contain the »ITH 
DUPLICATES phrase in the associated 
ALTERNATE RECORD KE¥. A specification 
of ONIQUEKEY requires that the COBOL 
program not have such a HITH DUPLICATES 
phrase. 

• UPGRADE specifies that this alternate 
index is to be kept up to date when its 
base cluster is modified. This is a 
required parameter. 

• PATHENTRY specifies the name of the 
alternate index, as given in the 

(NAME (name)) field for the related 
DEFINE ALTERNATEINDEX. This is a 
required parameter. 

• UPDATE specifies that the base 
cluster's upgrade set is to be 
allocated when the path is opened. 
This allows updating of alternate 
indexes (see UPGRADE above) , and is a 
required parameter. 

ADDITIONAL PARAMETERS: Additional 
parameters are valid for DEFINE CLUSTER, 
ALTERNATEINDEX, and PATH. Complete details 
on the use of these parameters are in the 
publication OS/YS Access Method Services. 



Defining an RRDS 



Defining an RRDS is quite similar to 
defining a KSDS. with the following 



modifications, the DEFINE CLUSTER portion 
of Figure 73 could be used to define an 
RRDS: 

1. Change INDEXED to NUMBERED. 

2. Remove the KEYS parameter. 

3. Remove the FREESPACE parameter. 

4. Change the RECORDSIZE parameter so 
that the average and maximum value 
specifications are the same. 



Defi ning an E SDS 

Defining an ESDS is quite similar to 
defining a KSDS. With the following 
modifications, the DEFINE CLUSTER portion 
of Figure 73 could be used to define an 

ESDS: 

1. Change INDEXED to NONINDEXED. 

2. Remove the KEYS parameter. 

3. Remove the FREESPACE parameter. 



Reugable Data gets 



If a COBOL 
data set for a 
data set again 
of processing) 
included in th 
specification, 
opened OUTPUT, 
"unloaded.") E 
KSDS data sets 
can be reused 



program wishes to use a VSAM 
workfile (that is, use the 
and again during the course 

, the REUSE parameter must be 

e DEFINE CLUSTER 
and the data set must be 
(Its status is then 

SDS and RRDS data sets and 
without alternate indexes 

in this manner. 
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Miscellaneous DEFINE Cluster C onsiderations FILE PROCESSING TECHNIQUES 



The control interval is the unit of 
transmission of data to and from main 
storage. VSAM determines the size of the 
control interval based upon the amount of 
BUFFEBSPACE specified and the size of the 
RECORDSIZE specified. If BUFFERSPACE is 
not specified and if the size of the 
records permits, VSAM uses the optimum 
size for the data component control 
intervals and 512 as the size of the index 
component control intervals. 



COBOL FILE PROCESSING CONSIDERATIONS 



The file processing considerations of 
importance to the COBOL programmer are: 
the file processing technigues available, 
the current record pointer, the START 
statement, and the error processing options 
available. 



The COBOL user has three different file 
processing technigues available to him: 
sequential, random, and dynamic (a 
combination of sequential and random) . The 
technique to be used is specified through 
the ACCESS clause of the SELECT statement. 



ESDS Proces si ng 



An ESDS can only be processed 
sequentially. Therefore, the ACCESS clause 
need not be specified since the default is 
sequential. 
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KSDS a nd RRDS Pro cessing 



CURRENT RECORD POINTER 



A KSDS or an RRDS can be processed 
sequentially, randomly, or both 
sequentially and randomly. To process 
sequentially, ACCESS IS SEQUENTIAL is 
specified. To process randomly, ACCESS IS 
RANDOM is specified. To process both 
sequentially and randomly, ACCESS IS 
DYNAMIC is specified. 



ACCESS IS DYNAMIC provides the greatest 
flexibility since most of the capabilities 
of both sequential and random processing 
are available. subsequent to an OPEN 
statement processing can be switched from 
sequential to random and vice- versa, as 
many times as desired. 



The current record pointer (CRP) , a 
conceptual pointer, is applicable only to 
sequential requests for ESDS, RRDS, and 
KSDS. Basically, the current record 
pointer indicates the next record to be 
accessed by a sequential request; the CRP 
has no meaning for random processing or 
output operations. The CRP is affected 
only by the OPEN, START and READ 
statements; it is not used or affected by 
the WRITE, REWRITE, or DELETE statements. 



In general, the last request on a file 
that establishes the CRP (OPEN, READ, or 
START) must have been successful in order 
for the sequential READ to be successful. 



PASSWORD USAGE 



Example 1: 

If the sequence of I/O operations on a 
file with ACCESS IS DYNAMIC and opened 1-0 
is: 



The following procedures must be used READ 
when password support is employed with the WRITE 
VSAM data sets: READ NEXT 



(After setting record key to 10) 
(After setting record key to 44) 



• Through Access Method Services (at 
DEFINE time) , the programmer must 
password-protect the base cluster (as 
opposed to the data and its index 
separately). This is the password 
specified with the RECORD or RELATIVE 
KEY. If the data set is a KSDS with 
alternate keys, then the programmer 
must also password-protect either the 
path to the base cluster via an 
alternate index, or the alternate index 
itself. This is the password specified 
with the ALTERNATE RECORD KEY. 

• In the COBOL program, the user must 
specify the correct level of the 
password: read-only, update, and so 
on. Failure to do so will cause a 
rejection of the action request which 
violates the protection. 

• In the COBOL program, the password (if 
present for the data set) must be 
specified for every ALTERNATE RECORD 
KEY defined in the program — regardless 
of whether any accessing will ever 
actually be done using them. (This 
requirement does not apply if the file 
is opened only for OUTPUT and the user 
does not request a dynamic invocation 
of Access Method Services via the 
AIXBLD option.) 

• All required passwords must be 
correctly specified for the file before 
the COBOL OPEN will succeed. 



the READ NEXT will get record 11 if the 
previous READ was successful. If the 
previous READ was not successful, the 
STATUS KEY will be set to 94 (No Current 
Record Pointer) when the READ NEXT is 
attempted. This occurs independently of 
the success of the intervening WRITE. 

Generally, a READ NEXT must be preceded 
by a request that establishes the CRP 
(OPEN, START, READ, READ NEXT) . If the 
request that establishes the CRP is 
unsuccessful, the READ NEXT causes the 
STATUS KEY to be set to 94. 

Example 2: 

In this example, ACCESS IS SEQUENTIAL is 
specified for a KSDS; therefore, records 
are retrieved in ascending key sequence 
starting at the position indicated by the 
CRP. 



OPEN INPUT 

(Set record 

START 

READ 

(Set record 

START 

READ 

READ 

READ 



key to 10) 



key to 5) 



(CRP at record with 
lowest key in file) 

(CRP at record 10) 
(Read record 10) 

(CRP at record 5) 
(Read record 5; CRP 

set to record 6) 
(Read record 6; CRP 

set to record 7) 
(Read record 7: CRP 

set to record 8) 
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Note that the CHP can be moved around 
randomly through the use of the START 
statement but all reading is done 
sequentially from that point. 

If the START request for record key 5 
had failed with no record found, the 
subsequent READ requests would have failed 
because there would have been no current 
record pointer. 

Example 3: 

In this example ACCESS IS DYNAMIC is 
specified. Therefore, records are accessed 
randomly if a READ is specified and 
sequentially if READ NEXT is specified. 
The highest key is 44. 



OPEN INPUT 

(Set record key to 5) 
SEAD 

BEAD NEXT 

SEAD NEXT 

(Set record key to 43) 
ST AST 

HEAD NEXT 

(Set record Key to 47) 

START 

READ NEXT 



(CRP is set to 
lowest key on file) 

(Read record 5; set 
CRP to record 6) 

(Read record 6; set 
CRP to record 7) 

(Read record 7; set 
(CRP to record 8 

(Position CRP to 

record 4 3) 
(Read record 43; set 

CRP to 44) 



(Fails - no CRP) 



The last READ NEXT failed because the 
preceding START was unsuccessful; in this 
data set there is no record 47. 

Example 4: 

In this updating example, ACCESS IS 
DYNAMIC is specified; the REWRITE statement 
does not affect the CRP. 



OPEN 1-0 



(Set record 
READ 

REWRITE 



READ NEXT 



(Set record 

REWRITE 



READ NEXT 



Key to 10) 



key to 74) 



(CRP is set to 
first record on 
file) 

(Read record 10; set 

CRP to record 11) 
(Updates record 10; 

CRP remains at 

record 1 1) 
(Read record 11; 

set CRP to record 

12) 

(Fails - record not 
found in this data 
set 

(Read record 12; set 
CRP to record 13) 



1st 


5 


2nd 


10 


3rd 


15 


4th 


20 


5th 


25 


6th 


30 


7th 


35 


8th 


40 


EN 1-0 





Note that although the last REWRITE failed, 
the following READ NEXT was successful. 



The REWRITE failed because record 74 was 
not read before the REWRITE was attempted, 

Example 5: 

In this example, ACCESS IS DYNAMIC is 
specified for a KSDS with an alternate 
record key, AIXKEY, defined. Assume that 
the file contains eight records whose 
primary and alternate key values are as 
follows: 

Record primary Key Alt ernate Key 



100 
70 
80 
85 
75 
50 
95 
55 



(CRP is set to the 
first record of file 
and the key of 
reference is the 
primary key) 

(set record key to 10) 

READ (without KEY clause) 

Read second record; 
set CRP to third 
record) 

(set alternate key to 50) 

READ KEY IS AIXKEY (the key of 

reference is the 
alternate key; read 
sixth record; set 
CRP to eighth 
record) 

READ NEXT (the key of 

reference remains 
the alternate key; 
read eighth record; 
set CRP to second 
record) 

(set primary key to 45 

and alternate key to 90) 

HRITE (write ninth record; 

CEP remains at 
second record; the 
key of reference 
also remains the 
alternate key) 
(read second record; 
CRP is set to fifth 
record) 
100) 
(CRP is set to first 
record; the key of 
reference is the 
alternate key) 
(read first record; 
CRP is set so that 
the next sequential 
read results in the 
AT END condition) 
(The AT END 



READ NEXT 



(set alternate key to 
START KEY = AIXKEY 



READ NEXT 



READ NEXT 
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condition is raised; 
CRP is undefined) 



The Importance of status Key 



OSE OF THE START VERB 



In some of the preceding examples, the 
START verb vas used to position the CRP. 
Then the READ (for ACCESS IS SEQUENTIAL) 
and READ NEXT {.for sequential processing 
when ACCESS IS DYNAMIC) retrieves the 
record pointed to by the CRP as established 
by the START. 

Example: 

05 RECORD-KEY. 
10 GEN11. 

15 GEN12 PIC 99. 
15 GEN13 PIC 99. 
10 GEN14 PIC 9. 

In this example, GEN12, GEN11, or 
RECORD-KEY could be used as the data-name 
in the "KEY IS relational data-name" option 
of the START statement. The lengths would 
be 2, 4, and 5 respectively. GEN13 and 
GEN14 could not be used as they are not in 
the leftmost part of RECORD-KEY. 

Assume that the value of RECORD-KEY is 
01472: 

• START file-name KEY=GEN1 1 would 
position the CRP to the first record on 
the file whose key has 0147 in the 
first 4 bytes. 

• START filename KEY > GEN12 would 
position the CRP to the first record in 
the file whose key has the first two 
bytes greater than 01. 



All errors in p 
whether a logic er 
COBOL programmer o 
external storage m 
the COBOL program. 
COBOL program, the 
the status of the 
Figure 74 indicate 
the Status Key and 
meanings. 



rocessing a VSAM file, 
ror on the part of the 
r an I/O error on the 
edia f return control to 
Upon return to the 

Status Key will indicate 
last request on the file. 
s the possible value of 

their associated general 



yarn ing: It is essential that all VSAM 
files have a Status Key associated with 
them and that the programmer always check 
the contents of the status Key after each 
I/O request. If status Key is not used 
(and an EXCEPTION/ERROR procedure is not 
present) , serious errors will go 
undiscovered by the program — which does not 
abend. The continued processing in such a 
situation may produce results that are not 
only destructive but difficult to detect. 



Inv alid Ke y 



If the INVALID KEY option is specified 
in the statement causing an invalid key 
condition, control is transferred to the 
INVALID KEY imperative-statement. Any 
EXCEPTION/ERROR declarative procedure 
specified for this data set is not 
executed. If the FILE-STATUS clause is 
specified, a value is placed into the 
Status Key to indicate INVALID KEY 
condition. 



ERROR PROCESSING OPTIONS 



The error processing options available 
to the COBOL programmer are INVALID KEY, 
EXCEPTION/ERROR procedure, and STATUS KEY. 
These options can be used in combination 
with each other. 



EXCEPTION/ERROR Procedure 



The EXCEPTION/ERROR procedure is invoked 
only when a file is in the open status. 
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i r 

Status Key 2} 
Value J 

j- 



Status Key 1 
Value 



Meaning 



Meaning 



Successful Completion 



| No Further Information 
, 



J Duplicate Key Found, And 
i Program Specified the 
| DUPLICATES Option 
_j 



At End (no next logical record, 
or an OPTIONAL file not avail- 
able at OPEN time) 



J No Further Intonation 
J 



No Further Information 



Invalid Key 



4- 



JSeguence Error 

H- 



I Duplicate Key Found, But 
j Duplicate Keys Not Allowed 



J No Record Found 



I 



Permanent Error {data check, 
parity check, transmission 
error) 



| Boundary Violation on WRITE 
J to VSAM indexed or relative 
J file (space not found to 
i add requested record) 



I No Further Information 
+ 



j Boundary Violation on WRITE 
j to sequential VSAM file 
j (space not found to add 
j requested record) 



Other Errors 



INo Further Information 
+ 



| Password Failure 



J Logic Error 
H 



|Sesource Not Available 

-i 



| No current Becord Pointer 
jFor Sequential Request 



| Invalid Or Incomplete File 
} Information 



| No DD Card 



) The data set was not pro- 
I perly closed; an implicit 
I VERIFY has therefore been 
J issued, and the file then 
I successfully opened. 



Figure 74. Status Key Values And Their Meanings 



Error , Handling Consi derati ons 



Figure 75 is a table of actions taken 
for all the combinations of AT END, INVALID 
KEY and EXCEPT ION/EH ROB Procedure based on 
the first character of the Status Key 
return. Note that the return is always to 



the next sentence unless the request that 
caused the error contained on AT END or 
INVALID KEY clause. Note also that the 
EXCEPTION/EEROS Procedure is executed only 
if the file is in the open status. 
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First Digit | 

of H 
Status Key 



No EXCEPTION/ERROR Procedure 
r 



AT END 

or INVALID KEY 



No AT END 

or INVALID KEY 



fith EXCEPTION/ERROR Procedure 



AT END 

or INVALID KEY 



No AT END 

or INVALID KEY 



Return to next 
sentence. 



Return to next 
sentence. 



Return to next 
sentence. 



Return to next 
sentence. 



Return to AT 
END/INVALID KEY 
address. 



Return to next 
sentence. 



Return to AT 
END/INVALID KEY 
address. 



Return to next sen- 
tence after execution 
Of EXCEPTION/ERROR 
Procedure. 



Return to AT 
END/INVALID KEY 
address. 



Return to next 
sentence. 



Return to AT 
END/INVALID KEY 
address. 



Return to next sen- 
tence after execution 
Of EXCEPTION/ERROR 
Procedure. 



Return to next 
sentence. 



Return to next 
sentence. 



Return to next 
sentence after 
execution of 
EXCEPTION/ERROR 
Procedure. 



return to next sen- 
tence after execution 
Of EXCEPTION/ERROR 
Procedure. 



Return to next 
sentence. 



Return to next 
sentence. 



Return to next 
sentence after 
execution of 
EXCEPTION/ERROR 
Procedure. 



Return to next sen- 
tence after execution 
Of EXCEPTION/ERROR 
j Procedure. 



Figure 75. Error Handling Actions Based on COBOL Program Coding. 



OPENING A VSAM FILE 



VSAM files can be opened INPUT, OUTPUT, 
EXTEND, or 1-0. 



Openi ng an Unloaded File 



An unloaded file is a file that has 
never contained records. It is normally 
opened OUTPUT or EXTEND. 

While certain types of unloaded files 
may also be successfully opened INPUT or 
1-0, the following conditions will occur if 
attempts are then made to access it. 

If unloaded file is opened INPUT and 
operation is: 

• READ sequential — will fail, with status 
key set to 10 

• READ random — will fail, with status key 
set to 2 3 

• START — will fail, with status key set 
to 23 



• Any other request — will fail, with 
status key set to 92 

If unloaded file is opened I-u and first 
operation is: 

• WRITE — will succeed, if a valid request, 
and any subsequent request will be 
treated as if made to a loaded file. 

• NOTE: A WRITE to a sequentially- 
accessed file is not a valid request 
when opened I-O. 

• READ sequential (if first 
request) — will fail, with status key 
set to 10 

• READ random {if first request) — will 
fail, with status key set to 23 

• START |if first request) — will fail, 
with status key set to 23 

• REWRITE/DELETE sequential (if first 
request) — will fail, with status key 
set to 92 

• REWRITE/DELETE random or dynamic (if 
first request) — will fail with status 
key set to 23 
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Opening an Empty File 

An empty file is a previously created 
file from which all records have been 
deleted. It can be opened EXTEND, INPUT or 
1-0. After opening, the first READ request 
will cause an AT END condition (Status Key 
= 10) or an INVALID KEY condition (Status 
Key = 23) , depending on the access mode of 
the file. An empty file cannot be opened 
OUTPUT. 



Open ing a _File_ - C onta i ning Records 



ords can be opened 
f a KSDS is opened 

to be added must 
er than the highest 
hen it was opened. 

higher the status 
For an ESDS, the 
the last record on 
t be opened EXTEND. 



A file containing rec 
INPUT, EXTEND or I-O. I 
EXTEND, the first record 
have its record key high 
record key on the file w 
If the record key is not 
key will be set to 92. 
records are added after 
the file. An RRDS canno 



OPEN Sta t us Key Va lues 



If any of the OPEN rules are violated 
the file is not opened and the status Key 
is set to the appropriate value. See 
Figure 76 for the OPEN Status Key values 
and their meanings. 



Dyna mic I n v o cat ion of Access Method 
Services for KSDS and BROS Data Sets 



( No te ; The following feature is 
provided only to assure compliance with the 
1974 ANS COBOL standard X3. 23-1974. Use of 
the feature will necessarily adversely 
affect execution-time performance.) 



As described earlier, the user must 
employ Access Method services to define all 
VSAM files and their indexes ahead of 
time — outside of the COBOL program. 
Normally at this time, the user specifies 
the size of the file*s records, and (for 
KSDS) the lengths and offsets of primary 
and any alternate keys. He also builds the 
actual alternate indexes. 



However, if he wishes, the user may 
choose to omit these elements of the 
definition procedure and have COBOL 
automatically perform them later when the 
file is opened for OUTPUT processing. 
COBOL does this by obtaining the correct 
record and key specifications from the 
program's source statements, and then 
issuing the Access method Services ALTER 
and BLDINDEX commands. 

If this is the user's choice, he must 
make it known to COBOL by including the 
object-time (GO-step) option AIXBLD. (He 
must also ensure that the Access Method 
Services program is available for his COBOL 
program to invoke.) 

For an REDS, COBOL will then fill in the 
record size information. For a KSDS, COBOL 
will fill in record size, and length and 
displacement for primary keys. If the KSDS 
has alternate keys, COBOL also fills in 
their length and displacement, and issues 
the BLDINDEX command. (Because the 
BLDINDEX command can be issued only after a 
base cluster is loaded, COBOL first fills 
it with dummy records, then issues the 
BLDINDEX command, and then erases them.) 

Because the large Access Method services 
program must be present when the COBOL 
program is run with this feature, 
substantial extra main storage is required. 
Use of the AIXBLD feature also requires the 
user to provide a SYSPRINT DD card for 
Access Method Services messages. If this 
card is missing, OPEN failure will result 
(Status Key = 95) . 
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If the Status Key 
given to the user 
was . . . 


either COBOL itself detected one of these 
conditions. . . 


... or VSAM found 
an error and returned 
one of the following 
VSAM error codes* 


00 


None 


100 (if AIXBLD was 
specified) 

128 (if file is 
optional) 

160 (if file was 
to be opened 
for input) 


30 


None 


132,144,164,176, 
184 


90 


Failure of an attempt to write a dummy 
record to or delete a dummy record from the 
file. Such a failure may occur in the 
following cases : 

— an indexed file is opened for OUTPUT and 
the access mode is either RANDOM or 
DYNAMIC . 

— a file to be opened 1-0 has just been 
created . 

— the object-time option AIXBLD was 
specified and the file has at ieast one 
alternate record key. 

Failure of attempt to use a CBMM macro. 

Failure of attempt to use a BLDL system 
macro; this macro is used when the 
programmer has specified the object-time 
option AIXBLD. 


96,108,116,192, 

196,200,204,208, 

212,216,220,224, 

236,240,244 (plus any 
other VSAM codes not 
appearing elsewhere in 
this table) 


91 


None 


152 


92 


The file to be opened is already open. 


4 


* COBOL 's VSAM-processing subroutines retrieve the VSAM return code from the 
ACBERFLG field of the Access Control Block (ACB) by issuing a SHOWCB macro, 
translate it into one of the status key values above (as prescribed by the 
ANS standard) , and move that value into the STATUS KEY field where it 
becomes accessible in the user's program. An explanation of the meanings 
of the VSAM return codes can be found in the VSAM Programmer's Guide. 



Figure 76. (Part 1 of 2) Status Key Values for OPEN Requests 



VSAM File Processing 187 



If the Status Key 
given to the user 
was. . . 


either COBOL itself detected one of these 
conditions. . . 


... or VSAM found 
an error and returned 
one of the following 
VSAM error codes* 


93 


COBOL cannot obtain sufficient virtual 
storage for: 

— the general work area used by the COBOL 
VSAM-interface modules. 

— the Access Control Block (ACB) address 
list area during the OPEN process. 

— the work area required for the 
invocation of Access Method Services. 

— processing of the uspr declarative. 


136 
168 


95 


The ENDRBA of a file to be opened OUTPUT 
is not zero. 

The length and/or offset of the key of 
each cluster do not match those in the 
catalog. 

A KSDS cluster is to be opened as a COBOL 
sequential (ESDS) file. 

An attempt was made to either alter the 
record size and/or key information of a 
cluster or build alternate indexes, and 
Access Method Services returned a non-zero 
return code . 


100 (if AIXBLD was 
not specified) 

104,108,148, 

160 (if a file 
is not to 
be opened 
for INPUT) 

180,188,232 


96 


No DD card is present for a path to be 
opened . 


128 (if a file 
is not 
optional) 


97 


OPEN is successful for a data set with 
alternate keys opened 1-0, EXTEND, or 
OUTPUT, and an implicit VERIFY has 
occurred. 


118 


* COBOL 's VSAM-processing subroutines retrieve the VSAM return code from the 
ACBERFLG field of the Access Control Block (ACB) by issuing a SHOWCB macro, 
translate it into one of the status key values above (as prescribed by the 
ANS standard) , and move that value into the STATUS KEY field where it 
becomes accessible in the user's program. An explanation of the meanings 
of the VSAM return codes can be found in the VSAM Programmer's Guide. 



Figure 76. (Part 2 of 2) Status Key Values for OPEN Bequests 



INITIAL LOADING OF RECORDS INTO A FILE 



Initial loading refers to writing 
records into a file after it is opened for 
the first time; this is distinctly 
different than writing records into an 
eipty file (a previously created file from 
which all records have been deleted) . 

When the file is unloaded and is opened 
EXTEND, it is processed exactly the same as 
it would be had it been opened OUTPUT. 

It is recommended that initial loading 
of records into a KSDS always be done 
sequentially. This assists in optimizing 
performance for the initial loading process 
as well as for any subsequent processing on 
the file, Loading records randomly does 



not conserve any free space in the file 
and, as a result, any future inserts 
require the file to be dynamically 
reorganized. 



WHITING RECORDS INTO A VSAM FILE 



The COBOL WHITE statement adds a record 
to a file; it does not replace an existing 
record on the file. The record to be 
written must not be larger than the maximut 
record size specified when the file was 
defined. 
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ESDS Considerations 



ESDS Considerations 



Records are written sequentially, 



KSD S C onsiderations - (ACCESS IS 

SEQfiMIIALl 



The records must be written in ascending 
Key sequence. If the file is opened 
EXTEND, the record keys of the records to 
be added must be higher than the highest 
record key on the file when the file was 
opened. 

For example, a file containing records 
whose records keys are 2, 4, 6, 8 and 10 is 
opened EXTEND; the following actions take 
place for the sequence of operations shown: 



WRITE (record key 

WRITE (record key 

WRITE (record key 

WRITE (record key 



If many records are to be added to the 
end of a file, it is recommended that 
sequential processing be used. It assists 
in optimizing processing for both the 
addition of records as well as later 
retrieval of them. 



KSDS Considerations - {ACCESS IS 



When a file has alternate keys, the 
records must be written using their primary 
keys. 



RR DS Consideratio ns 



8) 


SK 


= 92 


9) 


SK 


= 92 


12) 


SK 


= 00 


11) 


SK 


= 21 



The file must be opened 1-0; if not, the 
record is not rewritten and the Status Key 
is set to 92. The record to be rewritten 
must first be read by the COBOL program; 
the record may then be rewritten. If there 
was no preceding READ, or if the preceding 
READ was not successful, the record is not 
rewritten and the Status Key is set to 92. 
If an attempt is made to change the length 
of the record to be rewritten, the Status 
Key is set to 92. 



K SDS C on sideration s 



The file must be opened I-O; if not, the 
record is not rewritten and the Status Key 
is set to 92. The length of the record can 
be changed; the value of the record key 
cannot be changed. 

For ACCESS IS SEQUENTIAL, or files 
containing spanned records, the record to 
be rewritten must first be read by the 
COBOL program. The REWRITE then updates 
the record that was read. If the REWRITE 
is not preceded by a successful READ of the 
record to be rewritten, the rewrite is not 
done and the status Key is set to 92. 

For ACCESS IS RANDOM/DYNAMIC, and for 
records that are not spanned, the record 
to be rewritten need not be read by the 
COBOL program. To update a record, the key 
of the record to be updated is moved to the 
RECORD KEY data-name and then the REWRITE 
is issued. 

Rewiting must always be done by the 
primary key. COBOL does, however, allow a 
user to change the alternate key contents 
while rewriting the record. 



For a sequential request, the first 
record written will have relative record 
number one, the second two, the third 
three, and so on. If a RELATIVE KEY data 
item was included by the user in the file 
control entry statement, the relative 
record number of the record just written 
will be placed in the data item. 



READING RECORDS ON A VSAM FILE 



The COBOL READ statement is used to 
access records on a file. The file must be 
opened INPUT or 1-0; if not, the record is 
not read and the Status Key is set to 92. 



IWRITING RECORDS ON A VSAH FILE 



ESDS Consi deration s 



The COBOL REWRITE statement is used to 
replace an existing record in the file. 



The records are read in the sequence in 
which they were written. 
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KSDS Considerations - (ACCESS, IS 
SEQUENTIAL) 



Records are read sequentially beginning 
at. the position of the Current Record 
Pointer. If the Current Record Pointer is 
not defined at the time the READ is issued, 
the READ fails and the Status Key is set to 
94. 

The Current Record Pointer is undefined 
if a START is unsuccessful. For example: 



OPEN 1-0 filename 
READ 

(Set Record Key to 10) 

START 

READ 

(Set Record Key to 2 0) 

START 

READ 

READ 



READ 

(Set Record Key to 8) 

START 

READ 



CRP set to first 
record on file. 
First record is 
read. 

Fails — no record 
found. SK=23. 
Fails — no CRP. 
SK = 94. 

Successful. 
Record 20 is read. 
EOF encountered; 
SK = 10. 

Logic error;SK=92 

Successful. 
Record 8 is read. 



KSDS Considerations - (ACCESS IS RAN DOM) 



Records are read in the order specified 
in the COBOL program. For example, to 
read the record whose Record Key is 10, the 
RECORD KEY field must be set to 10 and then 
a READ is issued. 



KSDS Considerations - (ACCESS IS DYNAMIC) 



Records can be read sequentially or 
randomly. The READ NEXT statement is used 
for sequential accessing while the READ 
statement is used for random accessing. 
Within any given program, both sequential 
and random processing may be performed. 

SEQUENTIAL PROCESSING: Records are read 
sequentially beginning at the position of 
the Current Record Pointer. If the Current 
Record Pointer is undefined when the READ 
NEXT is issued, the record is not read and 
the Status Key is set to 94. The Current 
Record Pointer is undefined if the previous 
START or READ was unsuccessful. See the 
discussion of current Record Pointer for 
more details and examples of the effect of 
different COBOL statements on the 
positioning of the Current Record Pointer. 



RANDOM PROCESSING: Records are read 
randomly according to the value placed in 
the record key field. 



RRDS Considerations 



If a RELATIVE KEY data item was 
specified for a sequential READ, the 
relative record number of the record just 
read will be placed in the data item. 



DELETING RECORDS ON A FILE 



The COBOL DELETE statement is used to 
remove an existing record on a KSDS. 
DELETE cannot be used with an ESDS. 

The file must be opened I-O; if not, the 
record is not deleted and the Status Key is 
set to 92. 

For ACCESS IS SEQUENTIAL, or files 
containing spanned records, the record 
to be deleted must first be read by the 
COBOL program. The DELETE then removes 
the record that was read. If the DELETE 
is not preceded by a successful READ of 
the record to be deleted, the deletion 
is not done and the Status Key is set to 
92. 

For ACCESS IS RANDOM/DYNAMIC, and for 
records that are not spanned, the record 
to be deleted need not be read by the 
COBOL program. To delete a record, the 
key of the record to be deleted is moved 
to the RECORD KEY data-name and the 
DELETE is issued. 

STATUS KEY SETTINGS FOR ACTION REQUESTS 



Figure 77 is a summary of the status Key 
values that can occur for action requests. 
Status Key 92 has numerous possible causes 
as described below. 

Status Key 92 can be caused by: 

• Any request against a file that is not 
open. 

• Any request that is not allowed for the 
option that was specified with the OPEN 
statement. For example, an attempt is 
made to read a file that was opened as 
OUTPUT or an attempt is made to rewrite 
on a file opened as INPUT. 

• Any attempt to write or rewrite a 
record lonqer than the maximum record 
size specified when the file was 
defined. 
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Any attempted action on a file after 
the end-of-file condition has occurred. 
This is applicable to ESDS, BEDS, and 
KSDS; however, on an BEDS or KSDS a 
START or READ can be issued to set the 
Current Record Pointer to another point 
in the file so that processing may 
continue. For example: 

1. ACCESS IS SEQUENTIAL 



OPEN 
READ 
READ 
READ 
START 

READ 



Successful 

EOF encountered 

Logic error 

To reset Current Record 

Pointer 
Successful 



2. ACCESS IS DYNAMIC 



OPEN 
READ 
BEAD 
READ 



NEXT Successful 
NEXT EOF encountered 
NEXT Logic error 



READ Random READ to reset 

CRP 
READ NEXT Successful 

• An attempt to rewrite, when access is 
sequential, after an unsuccessful READ. 

• An attempt to delete, when access is 
sequential, after an unsuccessful READ. 
This applies to KSDS and RRDS only, 
since DELETE is not legal for ESDS. 



CLOSING A FILE 



If the user attempts to close a file 
which has already been closed, COBOL 
returns a status key value of 92. When 
performing a CLOSE request, VSAM itself may 
detect an error and return one of the 
following codes to COBOL: 132, 144, 164, 
176, or 184. COBOL will translate this 
VSAM code into a STATUS KEY of 30. 
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If the Status 
Key given to 
was. . . 


either COBOL itself discovered one of these 
conditions ... 


or VSAM found an 
error and returned 
one of the following 
VSAM error codes* 


02 


Permissible duplicate key follows for READ, or 
permissible duplicate key is created on one or 
more alternate indexes for WRITE or REWRITE. 
(This is the case when the feedback field of the 
RPL contains 8 but the LERAD exit is not taken.) 


None 


10 


READ is issued for the first time to an optional 
file. 

Sequential READ is issued to an empty file 
opened for INPUT. 


4 (if the request 
was not START) 


21 


None 


12,96 


22 


None 


8 


23 


Random READ or START issued to an empty file 
opened for INPUT. 

Relational operator GREATER THAN was specified 
in a START and the key contains HIGH-VALUE. 

Current record pointer failed for sequential 
READ because key used in the previous READ 
contained HIGH-VALUE. 


4 (if the request 
was START) 
16 
192 


24 


Relative record key contains a value larger 
than allowed. 


28 (if the file 
is not ESDS) 
148 


30 


SYNAD exit taken due to an I/O error. 


140 


34 


None 


28 (if the file 
is ESDS) 


90 


Failure of attempt to use a CBMM macro. 


32,64,68,72,76, 
80,84,104,112, 
116,132,136,144, 
196,200 

(plus any VSAM 
codes not 
appearing else- 
where in this 
table) 


* COBOL 's VSAM-processing subroutines retrieve the VSAM return code from the 
RPLFDBK field of the Request Parameter List (RPL) , translate it into one 
of the status key values above (as prescribed by the ANS standard) , and 
move that value into the STATUS KEY field where it becomes accessible in 
the user's program. An explanation of the meanings of the VSAM return 
codes can be found in the VSAM Programmer's Guide. 



Figure 77. {Part 1 of 2) status Key Values for Action Requests 
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If the Status 
Key given to 
was. . . 




either COBOL itself discovered one of these 
conditions. . . 


or VSAM found an 
error and returned 
one of the following 
VSAM error codes* 


92 


Impermissible request (action does not match 
file's open mode) . 

• 
File is not open. 

End-of-file condition had been raised by the 
previous operation, and a sequential READ is 
issued, or a REWRITE is issued when access mode 
is sequential, or a DELETE is issued and the 
access mode is sequential. 

Access mode is sequential, and the last I/O 
request for the file (prior to a REWRITE or 
DELETE) was not a successful READ. 

READ issued to an optional file is not the first 
READ request. 

The key value of a record to be added to an 
indexed file opened EXTEND is not the highest 
among record key values in the file. 


36,44,92,100, 
108,152,204 


93 


Insufficient virtual storage for the user 
declarative processing. 


20,24,40 


94 


The current record pointer (maintained by 
ILBOVIO) is undefined for this sequential READ. 


88 


* COBOL 's VSAM-processing subroutines retrieve the VSAM return code from the 
RPLFDBK field of the Request Parameter List (RPL) , translate it into one of 
the status key values above (as prescribed by the ANS standard) , and move 
that value into the STATUS KEY field where it becomes accessible in the 
user's program. An explanation of the meanings of the VSAM return codes 
can be found in the VSAM Programmer's Guide. 



Figure 77. (Part 2 of 2) Status Key Values for action Requests 



COBOL LANGUAGE USAGE HITH VSAM 



The COBOL language statements which are 
directly related to VSAM processing are in 
the publication IBM VS COBOL for OS/ VS. 
The following paragraphs are intended only 
to highlight and summarize the basic 
language statements used in writing a 
VSAH-file- processing COBOL program. 

The COBOL programmer can use VSAM in 
three basic ways: to write, to retrieve, 
and to update records in a data set. 
However, prior to processing a VSAM data 
set, it is an absolute necessity that the 
previously discussed Access Method Services 



functions are performed. Most significant 
to the COBOL programmer is whether the data 
set is defined as ESDS, KSDS or RRDS. 



WRITIHG A VSAM DATA SET 



The COBOL language statements frequently 
used to fill in a VSAM data set are 
summarized in Figure 78. Examples 1 and 2 
illustrate the creation of an ESDS and a 
KSDS respectively. 
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ESDS 



KSDS 



REDS 



t — 1 


r - — i 


r~ - — i 


1 T 


JEnvironment 


SELECT 


SELECT 


SELECT J 


J Division 


ASSIGN 


ASSIGN 


ASSIGN | 




FILE STATUS 


ORGANIZATION 


ORGANIZATION J 




PASSWORD 


IS INDEXED 


IS RELATIVE! 




ACCESS HODE 


RECORD KEY. 


RELATIVE KEY j 






ALTERNATE j 


FILE STATUS J 






RECORD KEY 








FILE STATUS 


PASSWORD J 






PASSWORD 


ACCESS HODE j 






ACCESS HODE 


i i 


JData 


FD entry 


FD entry 


1 1 

FD entry J 


| Division 
i 


LABEL RECORDS 


LABEL RECORDS 


| LABEL RECORDS | 
1 


i 

I Procedure 


OPEN OUTPUT 


OPEN OUTPUT 


1 

| OPEN OUTPUT J 


J Division 


OPEN EXTEND 


OPEN EXTEND 


WRITE J 




WRITE 


WRITE 


CLOSE | 




CLOSE 


CLOSE 





Figure 78- COBOL Statements Frequently Used for Writing into a VSAH Data Set 



Example 1: 

This example shows the creation of a 
COBOL ESDS. The FILE STATUS facility is 
used to monitor all I/O operations in the 
program. 

IDENTIFICATION DIVISION. 



ENVIRONMENT DIVISION. 



PARA3. 

WRITE OUTHASTER. 

IF CHK IS NOT = 00 GO TO CHKRTN. 

GO TO PARA2. 
PARA4. 

CLOSE INREC OUTREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
FINIT. 

STOP RUN. 
CHKRTN. 

DISPLAY »I/0 ERROR. STATUS KEY VALUE 
IS* CHK. 

GO TO FINIT. 



INPUT- OUTPUT SECTION. 
FILE-CONTROL. 

SELECT INREC 

ASSIGN TO UR-2540R-S-INFILE. 
SELECT OUTREC 

ASSIGN TO AS-OUTFILE 
FILE STATUS IS CHK. 



Note that in this example any Status Key 
return other than 00 causes transfer of 
control to paragraph CHKRTN. This user- 
created routine can determine the exact 
cause of the error by checking the Status 
Key. once the cause is determined, 
instructions can be issued according to the 
user's desired response to each type of 
error. 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECORDS ARE OMITTED 

DATA RECORD IS INHASTER. 
01 INHASTER PIC X{80) . 
FD OUTREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS ODTMASTER. 
01 OUTHASTER PIC X (80) . 
WORKING-STORAGE SECTION. 
77 CHK PIC 99 VALUE ZEROS. 
PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT INREC OUTPUT OUTREC. 

IF CHK IS NOT = 00 GO TO CHKBTN. 
PARA2. 

READ INREC INTO OUTHASTER 
AT END GO TO PARA4. 



Example 2: 

This example shows the creation of a 

COBOL KSDS; this program performs the same 

function as Example 1 except that now a 
KSDS is being created. 

IDENTIFICATION DIVISION. 



ENVIRONMENT DIVISION. 



INPUT-OUTPUT SECTION. 
FILE-CONTBOL. 

SELECT INREC 

ASSIGN TO UR-2540R-S-INFILE. 
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SELECT OUTREC 

ASSIGN TO DA-2319-OUTFILE 
ORGANIZATION IS INDEXED 
RECORD KEY IS ARG-1 
FILE STATUS IS CHK. 



DATA DIVISION- 
FILE SECTION. 
FD INREC LABEL RECORDS ARE OMITTED 

DATA RECORD IS INHASTER. 
01 INHASTER PIC X (80) . 
FD OUTREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS OUTMASTER. 
01 OUTMASTER. 

05 FILLER PIC X. 

05 ARG-1 PIC XXX. 

05 REM PIC X{76) . 
WORKING-STORAGE SECTION 
77 CHK PIC 99 VALDE ZERO- 
PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT INREC OUTPUT OUTREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
PARA2. 

READ INREC INTO OUTMASTER. 
AT END GO TO PARA4. 
PARA3. 

WRITE OUTMASTER. 

IF CHK IS NOT = 00 GO TO CHKRTN. 

GO TO PARA2. 
PARA4. 

CLOSE INREC OUTREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
FINIT. 

STOP RUN. 
CHKRTN. 

DISPLAY 'I/O ERROR. STATUS KEY VALUE 
IS' CHK. 

GO TO FINIT. 



Note that 
return oth 
control to 
created ro 
cause of t 
Status Key 
instructio 
user's des 
error. 

Example 3: 



in this example any status Key 
er than 00 causes transfer of 

paragraph CHKRTN- This user- 
utine can determine the exact 
he l/o error by checking the 

Once the cause is determined, 
ns can be issued according to the 
ired response to each type of 



This example also shows the creation of 
a COBOL KSDS, but with the addition of an 
alternate key; this program serves the same 
function as Example 2. 
IDENTIFICATION DIVISION. 



FILE-CONTROL. 

SELECT INREC 

ASSIGN TO US-2540R-S-INFILE. 
SELECT OUTREC 

ASSIGN TO DA-2319-OUTFILE 

ORGANIZATION IS INDEXED 

RECORD KEY IS ARG-1 

ALTERNATE RECORD KEY IS ARG-2 

FILE STATUS IS CHK. 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECORDS ARE OMITTED 

DATA RECORD IS INHASTER. 
01 INHASTER PIC X<80) . 
FD OUTREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS OUTMASTER. 
01 OUTMASTER. 

05 FILLER PIC X. 

05 ARG-1 PIC XXX. 

05 ARG-2 PIC XXXXX. 

05 REM PIC X (71). 
WORKING-STORAGE SECTION 
77 CHK PIC 99 VALUE ZERO. 
PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT INREC OUTPUT OUTREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
PARA2. 

READ INREC INTO OUTMASTER. 
AT END GO TO PARA4. 
PAR A 3. 

WRITE OUTMASTER. 

IF CHK IS NOT = 00 GO TO CHKRTN. 

GO TO PARA2. 
PARA4. 

CLOSE INREC OUTREC. 

IF CHK IS NOT = 00 GO TO CHKPTN. 
FINIT. 

STOP RUN. 
CHKRTN. 

DISPLAY 'I/O ERROR- STATUS KEY VALUE 
IS* CHK. 

GO TO FINIT. 

Note that in this example any Status Key 
return other than 00 causes transfer of 
control to paragraph CHKRTN. This 
user-created routine can determine the 
exact cause of the error by checking the 
Status Key. Once the cause is determined, 
instructions can be issued according to the 
user's desired response to each type of 
error. 



RETRIEVING RECORDS FROM A VSAM DATA SET 



ENVIRONMENT DIVISION. 



INPUT-OUTPUT SECTION, 



The COBOL language statements freguently 
used to retrieve records from a VSAM data 
set are summarized in Figure 79. Examples 
3 and H illustrate the retrieval of records 
from an ESDS and KSDS, respectively. 
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ESDS 



KSDS 



RRDS 



l""" - ' ' '■■ 1 


— i 





n 


r — i 


I Environment I 


SELECT 


SELECT 




SELECT | 


| Division 


ASSIGN 


ASSIGN 




ASSIGN | 






ORGANIZATION IS 


INDEXED 


ORGANIZATION IS INDEXED | 






RECORD KEY 




RELATIVE KEY | 






ALTERNATE RECORD 


KEY 


ALTERNATE RECORD KEY | 




FILE STATUS 


FILE STATUS 




FILE STATUS | 




PASSWORD 


PASSWORD 




PASSWORD | 




ACCESS MODE 


ACCESS MODE 




ACCESS MODE | 
.... i 


| Data 


FD entry 


FD entry 




1 

FD entry | 


| Division 
i 


LABEL RECORDS 


LABEL RECORDS 




LABEL RECORDS | 


i 

| Procedure 


OPEN INPUT 


OPEN INPUT 




OPEN INPUT | 


| Division 


READ.. .AT END 


READ 




READ | 




CLOSE 


CLOSE 




CLOSE | 



Figure 79. COBOL Statements Frequently Used for Retrieving Records From a VSAM Data Set 



Example 4. 

This example shows the retrieval of 
records from the ESDS created in example 1 
The records are then printed. 

IDENTIFICATION DIVISION. 



IF CHK IS NOT = 00 GO TO CHKRTN . 
FINIT. 

STOP RUN. 
CHKRTN. 

DISPLAY 'I/O ERROR. STATUS KEY VALUE IS 1 
CHK. 

GO TO FINIT. 



ENVIRONMENT DIVISION. 



INPUT-OUTPUT SECTION. 

FILF-CONTROL. 

SELECT INREC 

ASSIGN TO AS-OUTFILE 

FILE STATUS IS CHK. 

SELECT PREC 

ASSIGN TO UR-1403-S-PFILE. 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECORDS ARE STANDARD 

DftTA RECORD IS INMASTER. 
01 INMASTER PIC X (80) . 
FD PREC LABEL RECORDS ARE OMITTED 

DATA RECORD IS POUT. 
01 POUT PIC X (80) . 
WORKING-STORAGE SECTION. 
77 CHK PIC 99 VALUE ZERO. 
PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT INREC OUTPUT PREC. 
IF CHK IS NOT = 00 GO TO CHKRTN. 
PARA2. 
READ INREC INTO POUT AT END GO TO PARA4. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
PARA3. 

WRITE POUT. 

GO TO PAPA2. 
PARA4. 

CLOSE OUTREC PREC. 



Note that in this example any Status Key 
return other than 00 causes transfer of 
control to paragraph CHKRTN. This user- 
created routine can determine the exact 
cause of the error by checking the Status 
Key. Once the cause is determined, 
instructions can be issued according to the 
user's desired response to each type of 
error. 

Example 5: 

This example shows the retrieval of 
records from the KSDS created in example 2. 
Note that in the Procedure Division there 
is a switch from sequential processing to 
random processing; this is permitted since 
ACCESS IS DYNAMIC is specified in the 
Environment Division. 

IDENTIFICATION DIVISION. 



ENVIRONMENT DIVISION. 



INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

SELECT INREC 

ASSIGN TO OUTFILE 
ORGANIZATION IS INDEXED 
ACCESS IS DYNAMIC 
RECORD KEY IS ARG-1 
FILE STATUS IS CHK. 
SELECT PREC 

ASSIGN TO UR-1403-S-PFILE. 
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IDENTIFICATION DIVISION, 



05 


FILLER 


05 


ARG-1 


05 


ARG-2 


05 


ARG-3 


05 


FILLER 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECOFDS ARE STANDARD 

DATA RECORD IS INMASTER. 
01 INMASTER. 

PIC X. 

PIC XXX. 

PIC XX. 

PIC XX. 

PIC X(72) . 

FD PREC LABEL RECORDS ARE OMITTED 

DATA RECORD IS PODT. 
01 POUT PIC X (80) . 
WORKING-STORAGE SECTION. 
77 CHK PIC 99 VALUE ZERO. 
PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT INREC OUTPUT PREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
PARA2. 

MOVE 00 3 TO ARG-1 . 

START INREC. 
PARA3. 

READ INREC NEXT AT END GO TO PARA4. 

IF CHK IS NOT = 00 GO TO CHKRTN. 

IF ARG-2 IS = 02 GO TO PARA4. 

IF ARG-3 IS NOT = 73 GO TO PARA3. 

WRITE POUT FROM INMASTER. 

GO TO PARA3. 
PARA4. 

MOVE 101 TO ARG-1. 

READ INREC INVALID KEY GO TO CHKRTN. 

WRITE POUT FROM INMASTER. 

MOVE 103 TO ARG-1. 

READ INREC INVALID KEY GO TO CHKRTN. 

WRITE POUT FROM INMASTER. 
PARA5. 

CLOSE INREC PREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
FINIT. 

STOP RUN. 
CHKRTN. 

DISPLAY 'I/O ERROR. STATUS KEY VALUE 
IS • CHK. 

GO TO FINIT. 



Note that in this example any Status Key 
return other than 00 causes transfer of 
control to paragraph CHKRTN. This user 
created routine can determine the exact 
cause of the I/O error by checking the 
Status Key. Once the cause is determined, 
instructions can be issued according to the 
users desired response to each type of 
error. 



Example 6: 

This example shows the retrieval of 
records from the KSDS created in example 3. 
Since ACCESS IS RANDOM is specified in the 
Environment Division, random processing of 
the file is done in the Procedure Division. 



ENVIRONMENT DIVISION 



INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT INREC 

ASSIGN TO OUTFILE 

ORGANIZATION IS INDEXED 

ACCESS IS RANDOM 

RECORD KEY IS ARG-1 

ALTERNATE RECORD KEY IS ARG-2 

FILE STATUS IS CHK. 
SELECT PREC 

ASSIGN TO UR-1403-S-PFILE. 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS INMASTER. 
01 TNMASTER. 

05 FILLER PIC X. 
05 ARG1 PIC XXX. 
05 ARG-2 PIC XXXXX. 
05 ARG-3 PIC XX. 
05 ARG-4 PIC XX. 
05 FILLER PIC X(67) . 
FD PREC LABEL RECORDS ARE OMITTED 

DATA RECORD IS POUT. 
01 POUT PIC X(80) . 
WORKING-STORAGE SECTION. 
77 CHK PIC 99 VALUE ZERO. 
PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT INREC OUTPUT PPEC. 
IF CHK IS NOT = 00 GO TO CHKRTN. 
PARA2. 

MOVE 003 TO ARG-1. 
PARA3. 

READ INREC INVALID KEY GO TO CHKRTN, 

IF CHK IS NOT = 00 GO TO CHKRTN. 

IF ARG-3 IS = 02 GO TO PARA5. 

IF ARG-4 IS NOT = 73 GO TO PARA4. 

WRITE POUT FROM INMASTER. 

ADD 010 TO ARG-1. 

GO TO PARA3. 



PARAU. 



PARA5. 



PARA6. 



FINIT. 



SUBTRACT 001 FROM ARG-1. 
GO TO PARA3. 

MOVE 101 TO ARG-2. 

READ INREC KEY IS ARG-2 INVALID KEY 

GO TO CHKRTN. 

WRITE POUT FROM INMASTER. 

MOVE 103 TO ARG-2. 

READ INREC KEY IS ARG-2 INVALID KEY 

GO TO CHKRTN. 

WRITE POUT FROM INMASTER. 

CLOSE INREC PREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
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STOP RUN. user's desired response to each type of 

CHKRTN. error. 

DISPLAY 'I/O EEROR. STATUS KEY VALUE 

IS » CHK. 
GO TO FINIT. 

UPDATING A VSAM DATA SET 
Note that in this example any Status Key 
return other than 00 causes transfer of 

control to paragraph CHKRTN. This user The COBOL language statements frequently 

created routine can determine the exact used to update a VSAM data set are 
cause of the I/O error by checking the summarized in Figure 80. Examples 7 and 8 
Status Key. Once the cause is determined, illustrate the updating of an ESDS and KSDS 
instructions can be issued according to the respectively. 



198 



ESDS 



KSDS 



RRDS 



r _ ._ — ., 1 


- - ■"■- ■ - 1 






— i 
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(Environment | 


SELECT | 


SELECT 






SELECT 




j Division 


ASSIGN 


ASSIGN 






ASSIGN 






FILE STATUS | 


ORGANIZATION IS INDEXED { 


ORGANIZATION IS RELATIVE 






PASSWORD 


RECORD KEY 






RELATIVE KEY 






ACCESS MODE 


ALTERNATE RECORD KEY 




FILE STATUS 








FILE STATUS 






PASSWORD 








PASSWORD 






ACCESS MODE 








ACCESS MODE 


















__ j 


.. 


J 














1 


|Data 


FD entry 


FD entry 






FD entry 




| Division 


LABEL RECORDS 


LABEL RECORDS 






LABEL RECORDS 


J 


j Procedure 


OPEN EXTEND 


For ACCESS IS 


SEQUENTIAL: 


For ACCESS IS SEQUENTIAL: 


1 


J Division 


WRITE 


OPEN EXTEND 




OPEN 1-0 






CLOSE 


WRITE 
CLOSE 






READ .. AT END 
| REWRITE 






or 


or 






DELETE 
CLOSE 






OPEN 1-0 














READ ... AT END 


OPEN 1-0 












REWRITE 


1 READ ... AT END 












| REWRITE 












CLOSE 


| DELETE 

| CLOSE 

i ,„, ., , 








| 




\ 








1 






J For ACCESS IS 


RANDOM: 




For ACCESS IS RANDOM: 








| OPEN 1-0 






j OPEN 1-0 








1 READ 






READ 








| WRITE 






| WRITE 








1 REWRITE 






REWRITE 








| DELETE 






| DELETE 








| CLOSE 
• 






CLOSE 


4 




1 








1 






J For ACCESS IS 


DYNAMIC 


with 


|For ACCESS IS DYNAMIC with 








J Sequential Processing 




1 Sequential Processing 








J OPEN 1-0 






J OPEN 1-0 








| READ NEXT 


... AT END 


READ NEXT ... AT END 








| WRITE 






| WRITE 








| REWRITE 






I REWRITE 








J START 






| START 








f DELETE 






I DELETE 








} CLOS E 

i 






| CLOSE 

1 , 






1 






1 








\ For ACCESS IS 


DYNAMIC 


with 


|For ACCESS IS DYNAMIC with 








J Random Process in g 




1 Random Processing 








J OPEN 1-0 






| OPEN 1-0 








J READ 






| READ 








1 WRITE 






| WRITE 








i REWRITE 






| REWRITE 








J DELETE 






| DELETE 








J CLOSE 






\ CLOSE 





Figure 80. COBOL statements Frequently used for Updating a VSAM Data Set 
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Example 7: 

This example shows the updating of 
records from the ESDS data set created in 
Example 1. 

IDENTIFICATION DIVISION. 



Example 8: 

This example shows the updating of 
selected records in the KSDS created in 
Example 2; the records to be updated by the 
contents of CARDFILE. Note the use of the 
DELETE statement; this could not be used 
with an ESDS. 



ENVIRONMENT DIVISION. 



IDENTIFICATION DIVISION. 



INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT INREC 

ASSIGN TO AS-OUTFILE 
FILE STATUS IS CHK. 



DATA DIVISION. 

FILE SECTION. 

FD INREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS INMASTER. 
01 INMASTER. 

05 FLD1 PCI X<3) 

05 FLD2 PIC X (3) . 

05 FLD3 PIC X{74). 
WORKING-STORAGE SECTION. 
77 CHK PIC 99 VALUE ZERO. 
PROCEDURE DIVISION. 
PARA1. 

OPEN 1-0 OUTREC. 

IF CHK IS NOT = 00 GO TO CHKBTN. 
PARA2. 

READ INREC AT END GO TO PARA4. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
PARA3. 

IF FLD2 IS NOT = 373 GO TO PARA2. 

MOVE 374 TO FLD2. 

REWRITE INMASTER. 

IF CHK IS NOT = 00 GO TO CHKRTN. 

GO TO PARA2. 
PARA4. 

CLOSE INREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
FIN.IT. 

STOP RUN. 
CHKRTN. 

DISPLAY VI-0 ERROR. STATUS KEY 
VALUE IS* CHK. 

GO TO FINIT. 



Note that in this example any status Key 
return other than 00 causes transfer of 
control to paragraph CHKRTN. This user- 
created routine can determine the exact 
cause of the I/O error by checking the 
Status Key. Once the cause is determined, 
instructions can be issued according to the 
users desired response to each type of 
error. 



ENVIRONMENT DIVISION. 



INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

SELECT CARDFILE 

ASSIGN TO UR-2540R-S-INREC, 
SELECT INREC 

ASSIGN TO INFILE 
ORGANIZATION IS INDEXED 
ACCESS IS RANDOM 
RECORD KEY IS ARG- 1 
FILE STATUS IS CHK 



DATA DIVISION. 

FILE SECTION. 

FD CARDFILE LABEL RECORD IS OMITTED 

DATA RECORD IS INCARD. 
01 INCARD 

05 CARDKEY PIC XXX. 
05 FILLER PIC X{77) . 
FD INREC LABEL RECORDS ARE STANDARD 

DATA RECORD IS INMASTER. 
01 INMASTER. 

PIC X. 
PIC XXX. 
PIC XX. 
PIC XX. 
PIC X(7 2) . 



05 
05 
05 
05 
05 



FILLER 

ARG-1 

ARG-2 

ARG- 3 

FILLER 

WORKING-STORAGE SECTION. 
77 CHK PIC XX VALUE ZEROS. 



PROCEDURE DIVISION. 
PARA1. 

OPEN INPUT CARDFILE 1-0 INREC. 

IF CHK IS NOT == 00 GO TO CHKRTN. 
PARA2. 

READ CARDFILE AT END GO TO PARA3. 

MOVE CARDKEY TO ARG-1. 

READ INREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 

IF ARG-2 = 01 DELETE INREC RECORD 

GO TO PARA2. 

IF ARG-3 = 75 MOVE 74 TO ARG-3 

REWRITE INMASTER. 

GO TO PARA2 
PARA3. 

CLOSE CARDFILE INREC. 

IF CHK IS NOT = 00 GO TO CHKRTN. 
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INIT. 

STOP RUN. 
HKRTN. 

DISPLAY 'I/O ERROR. STATUS KEY 

VALUE IS 1 CHK 

'LAST RECORD PROCESSED IS* CARDKEY. 

GO TO FINIT. 



lote that in this example any Status Key 
eturn other than 00 causes transfer of 
rontrol to paragraph CHKRTN. This user- 
ireated routine can determine the exact 
;ause of the I/O error by checking the 
Status Key. Once the cause is determined, 
.nstructions can be issued according to the 
isers desired response to each type of 
»rror. 



of the first alternate record key defined 
would have to be ABCD 1 . The ddname for the 
alternate path of the second alternate record 
key defined would have to be ABCD2, and so on. 

If the combination of base cluster ddname 
and sequence number exceeds eight characters, 
the base cluster portion of the ddname must be 
truncated at the right to reduce the concatenated 
result to eight characters. For example , if a 
base cluster's ddname is ABCDEFGH, then the first 
alternate path's ddname should be ABCDEFG1 , the 
tenth should be ABCDEF10, and so forth. 

The following example shows the connection 
between a program using two alternate indexes 
and the required DD statements. The base 
cluster is named XYZ, and the first alternate 
index' pathname is PATHONE and the other's 
PATHTWO . 



JOB CONTROL LANGUAGE , FOR VSAM FILE 
PROCESSING 



JCL is greatly simplified for VSAM since 
ill VSAM data sets must be cataloged 
through Access Method Services. In most 
rases, specification of the following DD 
statement will suffice: 



//ddname DD DSNAME=dsname r DISP={OLD| SHR} 

The dsname must be the same as the one 
specified for this data set through Access 
Method Services. 

If the user specifies the COBOL option 
AIXBLD, then the DD statement must also 
include the parameter AMP=»AM0RG«, 

DD STATEMENTS FOR ALTERNATE INDEXES 

When alternate indexes are used in 
the COBOL program, the user must specify 
not only a DD statement for the base 
cluster, but also one DD statement for each 
alternate path. The ddname for the base 
cluster is the one declared in the COBOL 
program. However, no language mechanism 
exists to explicitly declare ddnames for 
alternate paths in the program. Therefore, 
the following convention has been estab- 
lished and must be adhered to by the user. 

The ddname for each alternate path is to 
be formed by concatenating its base cluster 
ddname with an integer — beginning with 1 for 
the path associated with the first alternate 
record defined for that file in the COBOL 
program, and being incremented by 1 for 
each path associated with each successive 
alternate record definition for that file. 
For example, if a base cluster's- ddname were 
ABCD, then the ddname for the alternate path 



//ABCD DD 
//ABCD1 DD 
//ABCD 2 DD 



DSN=XYZ ,DISP=0LD 
DSN=PATHONE , DISP=OLD 
DSN=PATHTWO , DISP=OLD 



FILE-CONTROL. 

SELECT filename ASSIGN TO ABCD 
RECORD KEY IS whatever 
ALTERNATE RECORD KEY IS CITY 
ALTERNATE RECORD KEY IS PRICE 

The key CITY relates to the alternate index 
whose pathname is PATHONE, and the key PRICE 
relates to the alternate index whose pathname 
is PATHTWO. 

DD STATEMENT FOR A USER CATALOG 



If a data set in a job step is defined 
in a user catalog, it is also necessary to 
identify the user catalog by means of 
either a JOBCAT {Example 1) or STEPCAT 
(Example 2) DD statement. 

Example 1: 



//EX1 JOB 
//JOBCAT DD 

// EXEC 

Example 2: 

//EX2 JOB 
// EXEC 
//STEPCAT DD 



DSNAME=usercatalogname, 
DISP=SHR 



DSNAME= user cat alognarae, 
DISP=SHE 



DD PARAMETERS USED HTTH VSAM 



Although the operating system does not 
disallow OS/VS DD parameters and 
subparameters that do not apply to a VSAM 
data set, the COBOL programmer should be 
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aware that some of the DD parameters and 
subparameters have certain additional 
meanings when used with VSAM. For complete 
information on the meanings of the OS/VS DD 
parameters and subparameters, as well as 
the potential problems which exist if care 
is not taken, see OS/VS Virtual Storage 
Acces s Method (VSA M) programmers Guide. 



VSAfl-ONLY JCL PARAMETERS 



VSAM has one JCL parameter of its own: 
AMP. AMP, and its associated 
subparameters, is used mainly in 
conjunction with specifications made 
through Access Method Services. The AMP 
parameter takes effect when the data set 
defined by the DD statement is opened. For 
details on the use and specification of 
AMP, see the VSAM Programmer's Guide. 



C0 NYEB TI8G NON-VSAM FILES TO VSAM FILES 



Both SAM and ISAM data sets can be 
converted to VSAM data sets so that they 
may be processed by a COBOL program using 
VSAM. The conversion is done through 
Access Method Services. 

Essentially, the conversion process 
consists of defining a VSAM data set as the 
target for the data set being converted. 
Then through the appropriate JCL and the 
REPRO command, the conversion is 
accomplished. 

For a complete description of the 
conversion process, see OS/VS VSAM Access 
Method Services. 



USING COBOL ISAM PROGRAMS WITH VSAM FILE S 



Existing COBOL programs written to 
process ISAM files can be used to process 
VSAM files by going through VSAM's ISAM 
interface. To do this, the programmer need 
only make some JCL changes in the COBOL 
ISAM program. 



The EXEC card should specify the desired 
processing program, as usual; the DD card 
should be changed to a VSAM DD card as 
described above under "Job Control Language 

| for VSAM File Processing." 

Certain AMP subparameters might be used 
for running an ISAM processing program with 



the ISAM interface. For complete details 
on the conversion process, see the V SAM 
Prog rammer's Guide . 

VSAM FEATURES HOT AVAILABLE THROUGH COBOL 



Not all of VSAM's facilities can be used 
directly through a COBOL program. These 
unavailable features include: 



• Alternate indexing for ESDS 

• Multiple string processing 

• skip-seguential processing (key- ordered 
sequential/direct) 

• Addressed-direct processing 

• Control-interval (low-level) processing 

• Journaling support 

• Alternate index as end-use object (as 
base cluster instead of path) 
processing 

• GET-previoas processing 

• Asynchronous processing 

It is possible to open a VSAM data 
set concurrently under two separate 
FDs in a COBOL program if the assign 
clauses of the SELECT .statements 
refer to the same DDNAME. When the 
ACB is generated, COBOL takes the 
GENCB default of 'DDN', which indicates 
DDNAME sharing to VSAM. In such a 
case, VSAM will share the same buffers 
and control blocks for the two ACBs, 
and data integrity is preserved. 

If the user program attempts to access 
records within the same control 
interval by using the two separate 
file definitions, lock-out may occur. 
If the program contains two SELECT 
statements for the file but uses 
different DDNAMEs, the file can still 
be opened. However, data set names 
are not shared, and VSAM will use 
two completely separate buffer pools 
and control block structures. In 
this case, the integrity of the data 
set is not preserved, and updates 
to the file may be lost. 

Note. Even when the spanned format is 
used, the COBOL restriction on the length 
of logical records must be adhered to 
(that is, a maximum length of 32,767 
characters) . 
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LISTER FBATOBB 



The lister feature of the IBM OS/VS 
COBOL Compiler can be used by the COBOL 
programmer to produce a COBOL source 
listing that is reformatted and 
cross-referenced to increase 
intelligibility and conserve space. 
Optionally, a reformatted source deck can 
be produced. The lister output can be 
produced either with or without compilation 
occurring. 



OPERATION OF THE LISTER FEAT3RE 



The lister accepts source programs 
written in OS/VS COBOL, analyzes the source 
statements, and produces the reformatted 
and cross-reference source program. The 
output is either in the form of a listing 
or as a listing and a punched deck. 



This reformatted sour 
indenting conventions ira 
to increase readability, 
cross-references between 
Procedure Division state 
PERFORM statements and p 
etc. Optionally, the li 
source deck that matches 
except that cross- re fere 
omitted. 



ce output follows 
posed by the lister 
and contains 
data items and 
ments, between 
aragraph names, 
ster produces a new 
the output listing 
nee information is 



Thus the lister c 
source decks for uni 
and for highlighting 
IF, GOTO, etc. , or i 
a cross-referenced s 
permanent documentat 
program, or for use 
analysis and debuggi 
permit printing the 
listing in two colum 
and the inclusion of 
statements. 



an be used to process 
formity of indenting 

of statements such as 
t can be used to obtain 
ource listing as 
ion of a production 
as an aid in program 
ng. various options 
Procedure Division 
ns to conserve space 

BASIS and COPY 



No tes : Lister ignores the carriage 
control statements SKIP and EJECT. When 
LISTER is in effect, the NO'S option has no 
meaning. 



PROGRAMMING CONSIDERATIONS 



The lister is designed to operate most 
efficiently on syntactically correct COBOL 
source, and does not have the expanded 
error handling of the full compiler. It is 
therefore highly recommended that the user 



programs first be compiled using the SYNTAX 
option, and syntax errors corrected before 
invoking the lister feature. If the lister 
function is used and there are syntactical 
errors, lister processing will be 
terminated. The syntax checking in the 
lister feature is different from the 
checking done by the standard compiler. 
Syntax checking is usually more stringent 
in the lister than in the compiler. Some 
syntax errors that are recognized but 
corrected by the standard compiler may be 
flagged as errors when using the lister. 

The listing produced by LISTER will be 
reformatted for that portion of the 
program that was syntactically correct. 
If LSTCOMP was specified, the SOURCE 
option will be forced on. 

Further notes: Since lister reformats the 
user's COBOL program, compilation of the 
program, if LSTCOMP is in effect, will be 
different from a non-lister compilation of 
the same program. For example: 

1. Lister seguence numbers may be 
different. 

2. SKIP/EJECT cards will have no 

functional value with lister. 

3. BASIS card will be dropped from the 
lister listings. 

4. FIPS messages will be based on the 

reformatted lister listings. 

5. Suppress option of COPY will have no 
effect. 

6. Seguence checking will not take place 

for a lister sum. 

7. Source statements copied from a 
user-created library as a result of a 
COPY statement are not reformatted. 
However, statements which begin in 
columns 8-11 will be indented to 
column 8 in the lister output, and 
those which begin in columns 12-72 
will be indented to column 12. 

8. Lister terminates upon detecting a 
syntax error in the COBOL source 
program. When such an error is 
detected, lister issues an error flag 
to signal that the following source 
cards are to be passed on without 
processing. Lister then treats the 
balance of the program as comment 
cards. 
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In addition to the condition mentioned 
above, unusual termination of lister can 
occur if the source program contains: 



• Too many (approximately 80 or 
more) consecutive *-comments 
cards . 

• Too many (approximately 100 or 
more) consecutive blank cards. 

• Too many (approximately 100 or 
more) consecutive cards for a 
single data item. 

If one of the above three conditions 
occurs, the file written on SYSUT2 is 
incomplete. 



THE LISTING 



The reformatted output listing is 
divided into four parts: 

1. k one-page introduction which 
summarizes briefly lister codes, 
conventions, uses. 

2. The Identification and Environment 
Divisions. 

3. Detailed, cross- referenced, 
reformatted Data and Procedure 
Divisions. 

4. The Summary listing. 
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These (except the introduction) are 
described briefly below, and in greater 
detail in subsequent sections. 



THE OUTPUT DECK 



The deck produced optionally by the 
lister may be saved either in card form or 
in a COPY/BASIS library. This output 
reflects the reformatted source program. 
The output deck is described in detail 
later in this chapter. 



REFORMATTING OF IDENTIFICATION AND 
ENVIRONMENT DIVISIONS 



The lister reformats the Identification 
Division statements only by imposing 
indenting conventions. Statements are 
indented two positions, and continuations, 
if any, are indented six additional 
positions. 

Environment Division statements are 
reformatted by imposing indenting 
conventions and by appending 
cross-reference information to SELECT 
statements in the FILE CONTROL section. 
Thus, in reading the FILE CONTROL section, 
there are direct references to the file 
description statements in the Data 
Division. 



Figure 81 is an example of reformatted 
Identification and Environment Divisions. 
(The note shown is not produced by the 
lister program.) 



DATA DIVISION REFORMATTING 



The lister reformats the Data Division 
principally by imposing indenting 
conventions. In addition, it aligns 
PICTURE, VALUE and other clauses vertically 
to improve readability and facilitate 
visual checking. such clauses as REDEFINES 
and OCCURS are highlighted as a result of 
the alignment. All indenting is with 
respect to the left margin, which contans 
the statement number. 

FDs and level-77 items are indented 
zero, level-01 items are indented two and 
level- 02 items are indented four. Level 03 
and lower are each indented two from the 
last higher level item, up to seven levels 
of indentation. Use of this convention, 
makes the overall structure of each file 
and group data item immediately apparent to 
the reader of the listing. 

The most striking change in the 
appearance for the Data Division listing is 



1 IDENTIFICATION DIVISION. 

2 PROGRAM-ID. TESTRUN. 

3 AUTHOR. PROGRAMMER NAMt. „„„.„ ,.,-.„.,-„ 

4 INSTALLATION. NEW YORK PROGRAMMING CENTER. 

5 DATE-mRITTEN. JULY 12t 1968. 

7 remarks" P this*program'has 6 been WRITTEN AS A SAMPLE PROGRAM FDR 
COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK 
AS INPUT. 

10 ENVIRONMENT DIVISION. 

11 CONFIGURATION SECTION. 

12 SOURCe-COMPUTER. IBM-3/0-168. 
12 OBJECT-COMPUTER. IBM-3/0-168. 

14 INPUT-OUTPUT SECTION. 

15 FILE-CONTROL. 

16 SEL t CT A FILE-l To UT - 2 , 0-S-S AMPLE. 

17 SEL^T^ILE^^ ^^^^ 



O 



Note: 



MJ Refers to FD statement numbers in the Data Division. 



Figure 81. sample Identification and Environment Division Output Listing 
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e Division statement 
ges, reads, tests, or 
the data item. Hhen 
eferences is too great 
the lister prints as 
om for, on the line, 
nder as a footnote at 
ge. 



The eight codes used in the Data 
Division are: 

C Data item changed (such as by ADD or 
HOVE) 

E Data item referred to by Environment 
Division statement (SELECT) or by some 
Procedure Division input/output 
operation (OPEN, CLOSE, INITIATE, etc.) 



Data item changed by REDEFINE or RENAHE 



Q Queried by IF, WHEN, or UNTIL 



R Referred to by a READ, ACCEPT, or 
similar statement 

U Data item unchanged (used as a source 
field) 

M Referred to by a WRITE, GENERATE, 
DISPLAY, or similar statement 

X Used as an index, subscript, or object 
of a DEPENDING ON statement 

Use of these codes is depicted in Figure 
82, which is an example of a reformatted 
Data Division. (The notes shown in the 
figure are not produced by the lister.) 
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25 
26 
37 
36 
39 
40 
4i 
42 
43 
44 
45 
46 
47 
46 
45 
50 
51 
£2 
£3 
£4 
55 
56 



DATA DIVISION. 
FILE SECTION. 
FD FILc-1 

label records are omitted 
block contains 5 RcCords 

RcCORD CONTAINS 20 CHARACTERS 

RtCORDING MOCE IS t- 

DATA RECORD IS RECoRD-1. 
01 RcCORD-1. 
02 FIELD- A 
FILt-2 

label records are omitted 
block contains s rccoros 
rccord contains 20 characters 

RtCORDING MOCE IS F 
DaTA RECORD IS RECuRD-2. 

01 RcCORD-2. 
02 FIELD-A 

WORKING-STORAGE SECTION. 

77 {COUNT SYNC PICTURE S99 

77 NGMotk SYNC PICTURE S99 
01 FILLER. 

02 alphabet picture Xi26) value "abcdefghijklmnopqrstuvwxyz". 
02 AlPHA redefines ALPHABET OCCURS 26 times picture X. 

02 ptPENDENTS PIC A(2bJ VALUE "01234012340123401234012340". 
02 OtPENO REDEFINES OcPENDENTS OCCURS 26 TIMES PICTURE X. ^ w 
01 WORK-RECORD. 15T^ 

05 name-field picture x. VS/ 

05 FiLLER , PICTURE X 

05 RtCORD-NO PICTURE 9999. 

05 filler,, picture x value is space. 

05 Location picture aaa value is "nyc. 

05 filler picture x 

05 nu-of-dependents picture xx. 

05 FiLLER PICTURE X(7) 

01 RECURDA. 



PICTURE IS X(20). 



PICTURE IS X(20). 




COMP. 
COMP. 



VALUE IS SPACE. 



VALUE SPACE. 
VALUE IS SPACES. 



75 W 
17E,82EfB6R,94E 



420 

41/69U 

44D 

43/71U 

74W T 75W,86Rt91M 

69C 



72C-« 



71Ct89Q,90C 



02 
02 



B REDEFINES A 



PICTURE S9(4) 
PICTURE S9(7) 



VALUE 1234. 
COMPUTATIONAL-3. 



56D 
55/70C f 7OU 



Notes: 

(7) FD referred to by SELECT statement in Environment Division. 

(l) Associated SELECT statement; E denotes Environment Division reference 
(or OPEN/CLOSE from Procedure Division) . 

(5) Procedure Division statement; R denotes that this statement reads this file. 

(T) Procedure Division statement; C denotes that this statement changes this data item. 

(D 13/ indicates that DEPENDENTS is defined in statement 43. 

The 44D following statement 43 indicates the same relationship between these two statements, 



Figure 82. Sample Data Division Output listing 
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PROCEDURE DIVISION REFORMATTING 



The lister reformats the Procedure 
Division by applying indenting conventions 
to nested IFs, GOTOs, etc., and by 
appending cross-references to sections and 
paragraphs to indicate that the stateaent 
is arrived at froa either a GO TO or a 
PERFORM. It also appends references to the 
Data Division so that the data itea being 
acted on can be found quickly. The five 
codes used in the Procedure Division are: 



A ALTER 

B (ALTER) to PROCEED TO 

G GO TO 

P PERFORM 

T (PERFORM) THRU 

Use of the codes G, P, and T is depicted 
in Figure 83. The A and B in Figure 83 are 
examples of lister* s footnoting of 
eleaentary 01- and 77-level data iteas ( not 
of ALTER and PROCEED TO). If additional 
such data items were present, they would be 
identified by footnotes lettered C, D, E„ 
and so forth. 
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57 PROCEDURE DIVISION. 



BEGIN. 

NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE T 
CREATED AND INITIALIZES COUNTERS. 

STEP-1. 

OPEN uUTPUT FILE-1. 

MOVE i.£RO TO KCUNT NOMoER. 

NOTE iHAT THE FOLLOWING CREATES INTERNALLY THE 
TO BE CONTAINED AN THE FILE, WRITES THEM 
AND DISPLAYS THErt ON THE CONSOLE. 



STEP-2. 
ADD 1 
ADD 1 



77P-*- 

TO KOUNT, 



58 
59 



61 
62 
63 
64 



66 
67 

6 a 

69 
7C 
71 
72 

73 
74 
75 

76 
77 

78 



80 
81 
82 
63 



85 
66 
87 

8£ 
89 
90 
91 
92 



93 STEP-8. 87G 

94 CLOSE FILE-2. 
9 5 STOP kUN. 



<D 



■ U MJUI1 1 J 

TO NOMBER, 
MOVE ALPHA (KCUNT) TO ixAMfc-FI ELD. 
COMPUTE B » B + 1. 

MOVE DEPEND (KCUNT) TO NO-QF-DEPENDENTS. 
MOVE uUMBER TO RECORO-wO. 

STEP-3. 77T 

DISPLAY WORK-RECORD UPLN CONSOLE. 
WRITE RECORD-1 FROM WOkK-RECORO. 

STEP-4. 

PERFORM STEP-2 THRU STtP-3 UNTIL KOUNT IS EQUAL 

TO 26. 
NOTE THAT THE FOLLOWING CLOSES OUTPUT ANO REOPENS IT AS 

INPUT. 

STEP-5. 

CLCSE FILE-1. 21 

OPEN INPUT FILE-2. 29 

NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES 
OUT EMPLCYEES WUH NO DEPENDENTS. 

(0 





96 — 


COBOL SPECIAL-REGISTERS 




97 


TALLY 




98 


PRINT-SWITCH 


BE 


99 


MORE-LABELS 


•—>. 


100 


RETURN-CODE 


Cu 


101 


LABEL-RETURN 


^H 


102 


SORT-RETURN 


\ 21 


103 


SORT-CORE-SIZE 


A,B 


104 


SORT-FILE-SIZE 


RECORDS 


105 


SORT-MODE-SIZE 


ON TAPE, 


106 


SORT-MESSAGE 




107 


CURRENT-DATE 




108 


TIME-OF-OAY 




109 


WHEN-COMPILED 


A 


110 


DEBUG-CONTENTS 


B 


111 


DEBUG-ITEM 


42, A, 46 


112 


DEBUG-LINE 


56,56 


113 


DEBUG-NAME 


44, A, 52 


114 


OEBUG-SUB-1 


B,48 


115 


OEBUG-SUB-2 




116 


DEBUG-SUB-3 


45 






27,45 


^~ J © 




66, 73, A 







STEP-6. 92G-* " ._ 

REAO fILE-2 RECORO INTu WORK-RECORD AT END 
GO TO STEP-8. 

STEP-7. 

IF NO-UF-DEPENDENTS IS EQUAL TO "0" 

MOVc "Z" TO NO-0F-*0fcPENDENTS. 
EXHIBIT NAMED WORK-RECuRO. 
GO TO STEP-6. 



29,45 
93 



52 
52 
45 
85 



29 



A-38 77 KOUNT 
B-39 77 NOMBEK 



SYNC 
SY.MC 



PICTURE S99 
PICTURE S99 



COM P. 
COMP. 



63C,67C,69X,71X,77Q 
63C68C72U 



Notes ; 
•0 Lister footnotes all occurrences of 77-level and elementary 01 -level data items. 
@ Statement 66 is arrived at through PERFORM in statement 77. 
Statement 77 contains the PERFORM of statement 66. 
Statement 85 is arrived at through GO TO in statement 92. 



figure 83. Sample Procedure Division Output Listing 



208 



SUMMARY LISTING 



The summary listing provides an overall 
view of the relationship among FDs, RDs, 
SDs, and SECTIONS. The entry for each of 
these major parts of the program consists 
of a title line shoving the statement 
number and the name of the file, record, or 
section and a series of counts (by 
reference type) for each of the categories 
"from" and "to." Intra references are also 
shown for SORKING-STORAGE and PROCEDURE; 



these are references within the section, 
file, or record, such as REDEFINES and 
PERFORM operations. "From" are the 
references from other parts of the program 
to this part and "to" are the references to 
other parts from this part. The other 
parts are identified by the numbers of 
their first statements; these numbers 
appear in the column just to the right of 
the words INTRA, FROM, and TO. 

Figure 84 is an example of a summary 
listing. 



1 IDENTIFICATION DIVISION. 

1C ENVIRONMENT DIVISION. 

11 CONFIGURATION SECTION. 

14 INPUT-OuTPUT SECTION. 

TC \\ i i:i|© 

16 DATA DIVISION. 
20 FILE SECTION. 



21 FILE-1 
FRCM 1* 
57 



1 E-l 

3 E-2.W-1 



I© 



25 FILE-2 
FRCM 14 1 E-l 

57 3 E-2.R-1 

27 WORKING-STORAGE SECTION 
INTKA _3 D-3 

FRCM 57 



21 C-9,Q-2tR-ltU-4,W-3,X-2 
57 PROCEDURE DIVISION. . , ft \ 

1C " ---... 



3 E-2.H-1 

3 E-2.R-1 

21 C-9,0-2, 



l,U-4 t W-3 f X-2 
COBOi. SPECIAL-REGISTckS — 



55 A 

42 ALPHA 

41 ALPHAdET 

56 B , 
58 BEGIN 

1G7 CURRENT-DATE,, 
liO C£ BUG-CONTENTS 

111 DEBUG-ITEM 

112 DEBUG-LINE 

113 OEBUG-NAME 

114 DEBUG-SUB-1 

115 CEBUG-SU6-2 

116 CEBUG-SUB-3 
44 DEPENu 

43 DEPENjENTS 

28 FIELD-A 
lb FIELD-A 
21 FILE-1 

29 FILE-t 
j8 KCUNT 

101 LABtL-RETURN 

50 LOCATION 

99 MORE-cABELS 

46 NAME-rlELD 

52 NO-OF-OEPENDENTS 

j9 NCMBEx 

98 PRINT-SWITCH 

48 REC0Ru-N0 

27 RECORu-1 

J5 RECORj-2 

3 4 RECCRjA 
loO RETURW-C00E 

103 SORT-cURE-SIZE 

104 S0RT-*-ILE-SIZE 
106 SORT-MtSSAGE 

105 SORT-MuDt-SlZE 
1U2 SCRT-n.fcTURN 

61 STcP-1 
06 STEP-*. 
73 STEP-^ 
76 STEP-4 
80 STEP-:. 
o5 STEP-o 
88 STEP-/ 
V3 STEP-c 
97 TALLY 

108 TIME-uF-DAY 

109 WHEN-COMPILED 
45 WORK-KtCORO 



(T) The INPUT-OUTPUT section contains references to one data item 
in FILF-1 and one data item in FILE-?. 

(2) FILE-1 is referenced once from the INPUT-OUTPUT section and three 
times from the Procedure Division. 

(t) The Procedure Division contains four intra references. 



Figure 84. Sample Summary Listing 
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THE SOURCE LISTING 



The source listing of the 
Identification, Environment, and Data 
Divisions may be considered as having three 
"columns." The leftmost contains a 
statement number, or is blank if the line 
is either a comment or a continuation of 
the preceding statement or line- The 
second contains the reformatted COBOL 
statements. The third (not present as an 
independent column in the Procedure 
Division) contains references to or from 
other statements in the source program. 
Thus, each line of the output listing 
contains a numbered source statement or its 
unnumbered continuation, and a reference or 
series of references to all other 
statements in the source program that refer 
to it. If the series of references is too 
long to fit on the line, the lister prints 
as many as will fit, followed by a letter 
indicating a footnote. The footnote 
contains the remainder of the references. 



The source listing of the Procedure 
Division is normally printed in 
double-column format, with each column 
divided as described above. This format 
approximately doubles the span of logic 
that can be seen on one page or one 
facing-page spread. 



Regardless of whether the 
follows indentation convent! 
indents statements according 
and according to hierarchy w 
applicable. This feature of 
makes file and record struct 
visible and also helps to id 
of related statements such a 
nesting of IPs. 



source code 
ons, the lister 

to their type, 
here 

the lister 
ure immediately 
entify groups 
s IF/ELSE and 



Note : If blank lines are present in the 
original source, the lister eliminates 
them and renumbers the statements 
accordingly. 



Format Conventions 



New statements are indented from the 
left margin, which contains the statement 
number. The lister treats the following as 
new statements; 

• Division and Section headers 

• Paragraph names 

• Level numbers or level indicators (FD, 
RD, etc.) 



• Verbs 

• ELSE/OTHERWISE 

• AT END (only when following SEARCH). 

Indentation of the new statement is made 
according to the following rules: 

1. Data Division 

• FDs and level 77 items are indented 
zero. 

• Level 01 items are indented zero in 
the Linkage and Working Storage 
sections and two in the File and 
Report sections 

• Each subseguent lower level within 
an 01 item is indented two more than 
the preceding higher level, up to a 
maximum of 14 character positions or 
7 levels. 

2.'" Procedure Division 

• Section names are indented zero 

• Paragraph names are indented two 

• Unconditionally executed verbs are 
indented four 

• Verbs executed under a single 
condition, such as IF or AT END, are 
indented six 

• The first IF in a nest is indented 
four, subseguent nested IFs are 

indented an additional two at each 
level up to a maximum of 14 character 
positions or 6 levels. 

• ELSEs are indented to the same 
position as the IF to which they 
correspond. 

3. Continuation lines in all divisions 
are indented six with respect to the 
first line of the continued statement. 

Word spacing within a statement and on 
continuation lines is usually one space. 
Hithin the Data Division, however, PICTURE 
and VALUE are aligned as nearly as possible 
into columns so that they may be found and 
compared easily. Words are never split at 
the end of a line unless the word to be 
split is a nonnumeric literal that will not 
fit on a single continuation line. 
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Refere nces appear to the right of the number of blanks available on the line. 

statement or continuation line. References Each reference consists of a statement 

following paragraph or section names appear number and a type indicator. 

immediately to the right of the name, 

separated by a blank. References following When references are in series, they are 

other types of statements appear as far to separated by commas and are in ascending 

the right as possible depending on the order. 
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Within the Data Division, a reference 
series nay end with an alphabetic footnote 
indicator. The footnote contains the 
remaining references to that data item. 



In the Procedure Divi 
nay also be a footnote i 
footnote is different in 
the Procedure Division-, 
actually an on- page repl 
Division statement refer 
footnoted statement. Th 
complete with all other 
data item from other por 
program. To conserve sp 
the lister does not repe 
appears at the bottom of 
preceding pages but inst 
footnote letter in the n 



sion, the reference 

ndicator, but the 
appearance. In 
the footnote is 

ica of the Data 

red to by the 

is replica is 

references to the 

tions of the 

ace in the listing, 

at a footnote if it 
either of the two 

ead reuses the same 

ew reference. 



G GO TO 

P PERFORM 

T (PERFORM) THRU 



THE SUMMARY LISTING 



The summary listing 
analysis and as a troub 
Using the summary listi 
ascertain quickly which 
referred to, which proc 
most often, and the nat 
references. The number 
undefined symbols and t 
incorrectly coded COBOL 
be ascertained. 



is useful both as an 
leshooting aid. 
ng, the user can 

data areas are most 
edures refer to them 
ure of those 

of references to 
he number of 

statements can also 



lY.pe„ indicators 



As mentioned above, a reference consists 
of a statement number and a type indicator. 
The type indicator provides immediate 
information as to what is being done by the 
statement referred to. 

Two sets of type indicators are used by 
the lister: one for the Data Division and 
one for the Procedure Division, within the 
Data Division, the type indicators are: 

C Data item changed (such as by ADD 
or MOVE) 

D Data item REDEFINED or RENAMED 

E Data item referred to by 

Environment Division statement 
(SELECT) or by some Procedure 
Division input/output operation 
(OPEN, CLOSE, INITIATE, etc.) 

Q Queried by IF, WHEN, or UNTIL 

R Referred to by a READ, ACCEPT or 
similar statement 

U Data item unchanged (used as a 
source field) 

W Referred to by a WRITE, GENERATE, 
DISPLAY, or similar statement 

X Used as an index, subscript, or 

object of a DEPENDING ON statement 

Within the Procedure Division, the type 
indicators are: 

A ALTER 

B (ALTER) TO PROCEED TO 
E INPUT or OUTPUT PROCEDURE (SORT 
Feature) 



General Appearance 



Each division or section header, and 
each FD, RD, or SD begins a new entry in 
the summary listing. The entry consists of 
the header line, and beginning on the next 
line, the total number of each kind of 
reference to that section from within 
itself (INTRA) , and from outside itself 
(FROM) . These are followed by similar 
information for references the section 
makes to others outside itself (TO). The 
type indicators used for references are the 
same as those used in the source listing. 

In large programs, with either no 
sections or very large sections in the 
Procedure Division, the lister summary may 
not be very helpful. This can be remedied 
by adding SECTION statements to the source 
program at appropriate points. If SECTION 
statements are being added to a program 
that already contains some, it is very 
important to make certain that both 
implicit and explicit reference qualifiers 
are not invalidated. 



THE OUTPUT DECK 



Optionally, the 
COBOL source deck 
reformatted source 
be saved in a BASI 
as input to the co 
cards. As a resul 
new deck may conta 
original, but the 
enough to cause an 
compilation time, 
from the listing a 



lister can produce a new 
that reflects the 

listing. This deck may 
S library, used directly 
mpiler, or punched into 
t of reformatting, the 
in more cards than the 
difference is not great 
y appreciable increase in 

The output deck differs 
s follows: 
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1. References, footnotes, and blank lines 
are omitted. 

2. Literals will be repositioned if 
needed to assure proper continuation. 

3. Statement numbers are converted to 
card numbers. 

a. The statement number is multiplied 
by 10, and leading zeros added as 
necessary to fill columns 1 
through 6. 

b. Comment and continuation cards are 
numbered one higher than the 
preceding card. 



SPECIFYING THE LISTER 



The lis 
PAKM field 
compiler o 
options th 
the format 
output. E 
specified 
meaning, u 
batch comp 
programs a 
lister fea 
specified 
card — even 
specified 



ter feature is 

of the EXEC c 

ptions. The c 

at are selecte 

and contents 
it her LSTONLY 
for the other 
nless BATCH is 
ilation, if so 
re to be com pi 
ture, L120 or 
in the PARM fi 
if LSTCOMP or 
on the CBI car 



specified in the 
ard through five 
orabi nation of 
d determine both 
of the lister 
or LSTCOMP must be 
options to have 

specified. In a 
me or all of the 
led using the 
L132 must be 
eld of the EXEC 

LSTONLY are 
d. 



FDECK 

NOFDECK 

indicates whether a copy of the 
reformatted source program is to be 
written on the SYSPUNCH data set. 
Since FDECK has meaning only with 
either LSTONLY or LSTCOMP, the lister 
output will be both a reformatted 
listing and a reformatted deck. COPY 
statements within the source program 
will be produced as COPY statements, 
or, if CDECK is in effect, the 
expansion of the COPY statement will 
be produced. 



CDECK 

10CDECK 

indicates whether or not COPY 
statements are to be converted to 
comment statements in the output 
listing and the COPY members are to be 
expanded. CDECK may be specified with 
FDECK or NOFDECK. With FDECK, the 
source deck produced will contain the 
expansion of COPY statements; with 
NOFDECK, only the expansions of COPY 
statements are produced. 



LC0L1 
LCQL2 



indicates whether the Procedure 
Division part of the listing is to be 
in single-or double- column format. 



The five lister options are described 
below. Note that the IBM-supplied defaults 
are indicated by an underscore; they can be 
changed when the compiler is installed. 
The lister options are as follows: 



indicates whether the length of each 
line of the reformatted listing is to 
be 12 or 132 characters long. 



LSTONLY 

LSTCOMP 

NOLST 

indicates whether the lister feature 
is to be used. LSTONLY specifies that 
a reformatted listing is to be 
produced but that no compilation is to 
occur. LSTCOMP specifies that both a 
reformatted listing is to be produced 
and compilation is to occur in the 
same job step. 
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SYMBOLIC DEBUGGING FEATURES 



A programmer using the IBM OS/YS COBOL 
Compiler under the IBM Operating System, 
has several methods available to him for 
testing and debugging his programs. Use of 
the symbolic debugging features are 
described in detail in this chapter. 



"Appendix A: A sampl 
an example of a program 
symbolic debugging featu 
"Program Checkout" conta 
useful for finding the i 
causes the abnormal term 
correcting the problem. 
"Output" and "Using the 
Feature" include a discu 
output and a description 
checkpoints and restarti 
respectively. 



e Program" contains 
run without the 
res. The chapter 
ins information 
nstruction that 
in at ion and then 

The chapters 
Chec kpoint/fiestart 
ssion of compiler 

of taking 
ng programs. 



Note: The program product IBM OS CO 
Interactive Debug (Program Number 57 
enables the user to debug his COBOL 
programs from a TSO terminal. To be 
acceptable for Interactive Debug, a 
must be compiled with the TEST compi 
option. TEST overrides FL08, STATE, 
and COUNT. However, note that TEST 
be specified with BATCH, since BATCH 
overrides TEST. TEST will also be 
cancelled if the program contains US 
DEBUGGING statements. Interactive D 
described in greater detail in the " 
Checkout" part of this publication. 



BOL 
34-CB4) 



program 
ler 

SYMDMP 
may not 



E Foe 
ebug is 
Program 



USE OF THE SYMBOLIC DEBUGGING FEATURES 



As an aid to debugging, compiler options 
can be reguested that provide additional 
diagnostic information for an abnormal 
termination other than one caused by 
"Canceled by Operator" or exceeding the 
system-state time slice. Three user 
options are available for object-time 
debugging — the statement number option 
(STATE) , the flow trace option (FLOW) , and 
the symbolic dump option (SYMDMP). 

The STATE option causes the number of 
the card for the last verb executed before 
termination to be printed out. The FLOW 
option causes a trace of the last 
user-specified number of procedures 
executed to be printed out (with a default 
of 99). Both STATE and FL08 cause the 
PBOGHAM-ID, the completion code, and the 
last problem PSH to be printed out. The 
SYMDMP option enables the user to reguest a 
symbolic formatted dump of the data area of 



the object program for an abnormal 
termination, or to reguest dynamic dumps of 
data areas at strategic points during 
execution. 

Use of these features reguires no source 
language coding; rather the user specifies 
these options at compile time, through job 
control language. Operation of the SYMDMP 
option is dependent on execution-time 
control cards. Figure 86 illustrates the 
output generated for each of these 
features. 

Hhen any of the debugging options is 
specified, the programmer must: 

• Reguest the option at compile time by 
specifying it in the PARS field or, if 
a cataloged procedure is used, in the 
PAHM.COB field. 

• Include a //SYSDBOUT DD card for the 
debug output data set at execution 

time. 

• Make the COBOL library available at 
execution time by specifying the 
following DD statement: 

//STEPLIB DD DSN=subr-libname,DISP=SHB, 
V0L=SE8= volser, NIT= unit 

(This is necessary because certain 
COBOL library subroutines are loaded 
dynamically from the subroutine library 
only as needed; they are not 
link-edited into the COBOL object 
program.) 

• If the COBOL program being debugged 
is to be invoked from a higher-level 
non-COBOL program, the programmer must 
ensure that the non-COBOL program calls 
the COBOL library subroutine ILBOSTPO 
before calling any COBOL program. For 
further information on this point, see 
the section "calling and Called 
Programs" in this manual. 



STAT E Option 



If the STATE option is in effect and an 
abnormal termination occurs, the printed 
output includes the compiler-generated card 
number or, if NUM is in effect, the card 
seguence number for the last verb executed. 
Violation of the rule against mixing RES 
and NORES programs in a single run unit may 
result in erroneous information from STATE. 
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fLQW Option 



If the FLOW option is in effect, a 
formatted list containing the PRGGRAH-ID 
and either the compiler-generated card 
number or the line number (if NUH is in 
effect) of the last n executed procedures 
is printed on SYSDBOUT. The number of 
procedures traced can vary from 1 to 99 and 
is specified by the programmer. 

The number of procedures to be traced may 
be specified at compile time via either the 
PARH parameter or, if a cataloged procedure 
is used, the PARH- COB field. This number 
may be overridden at execution time via the 
PARH parameter or, if a cataloged procedure 
is used, the PARH- GO parameter- If the 
number of procedures traced is specified at 
neither compile time nor execution time, 
either the default value of 99 or the value 
specified at program product installation 
will be employed. When using FLOS or 
NOFLOW at execution time, the option must 
be preceded by a slash "/"• (See Figure 8 
for an example.) 



If batch compilation is 
be specified at compile ti 
effect for every program i 
suppress a trace for a par 
within the batch, the prog 
specify NOFLOW at executio 
last parameter in the PARH 
program, or change the CBL 
information, see the secti 
the compiler" and "Options 



used, FLOW can 
me and remain in 
n the batch- To 
ticular program 
rammer should 
n time as the 

field for that 

card. For more 
ons "Options for 

for Execution." 



Note: The FLOW option is completely 
independent of the READY/RESET TRACE 
feature of the debugging language. 



By specifying a //SYSDTERM DD card in 
addition to the //SYSDBOUT DD card, dynamic 
dump output will be written onto SYSDTERM 
while the abend dump output will go to 

SYSDBOUT. SYMDMP output will be 
formatted at 55 lines to the page. 

Note; The TSO programmer should assign 
SYStyTERH to the terminal since dynamic dump 
output is interruptable. SYSDBOUT should 
be assigned to a direct access data set 
which could be listed at the terminal after 
the ABEND is complete. 

The abnormal termination dump consists 
of the following parts: 

1. An abnormal termination message, 
including the number of the statement 
and of the verb being executed at the 
time of an abnormal termination . 

2. Selected areas in the Task Global 
Table. 

3. A formatted dump of the Data Division 
including: 

(a) For an SD — the card number, the 
sort- file- name, the type, and the 
sort record. 



(b) For an FD — for VSAH: OPEN/CLOSE 
status, card number, organization, 
access mode, last I/O operation, 
file status, and the fields of the 
record. For non-VSAM: the card 
number, the file-name, the type, 
the ddname, the DECB and/or DCB 
status, the contents of the DECB 
and/or DCB in hexadecimal, and the 
fields of the record; also, for 
QSAH, the file status. 



SY HDHP O ption 



If the SYHDHP option is in effect, a 
symbolic formatted dump of the object 
program* s data area is produced when the 
program abnormally terminates. (The SYHDHP 
option cannot be used if the source program 
contains USE FOR DEBUGGING and WITH 
DEBUGGING HODE.) This option also enables 
the programmer to request dynamic dumps of 
specified data-names at strategic points 
during program execution. If two or more 
COBOL programs are link-edited together and 
one of them terminates abnormally, a 
formatted dump is produced for all programs 
in the calling sequence compiled with the 
SYHDHP option, up to and including the main 
program in the reverse order of their 
calling sequence. (The terminating program 
itself need not have been compiled with the 
SYHDHP option.) 



(c) For an UQ — the card number, the 
report-name, the type, the report 
line, and the contents of 
PAGE-COUNTER and LINE-COUNTER if 
present. 



(d) For a CD — the CD itself in its 
implicit format, as well as the 
area containing the message data 
currently being buffered. 



(e) For an index name — the name, the 
type, and the contents in decimal 
which represents an actual 
displacement from the beginning of 
the table that corresponds to an 
occurrence number in the table. 
The value is calculated as the 
occurrence number minus one, 
multiplied by the length of the 
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entry that is indexed by this 
index-name. 
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Ob ject -Time Control C ar ds 



The operation of the SYMDMP option is 
determined by two types of control cards: 

Program-control card — required if 
abnormal termination and/or dynamic 
dumps are requested. 

Line-control card — required only if 
dynamic dumps are requested. 



Syntax Rubles : The fields of both the 
program-control card and the line-control 
card must conform to the following rules: 

1. Control cards are essentially free 
form, i.e., parameters coded on these 
cards can start in any column. 
However, parameters may not extend 
beyond column 71. 

2. Each parameter except the last must be 
immediately followed by a comma or a 
blank. 

3. Ho commas are needed to account for 
optional parameters that are not 
specified. 

4. All upper-case letters in IBM 
documentation represent specifications 
that are to appear in the actual 
statement exactly as shown. 

5. All lower-case letters represent 
generic terms that are to be replaced 
in the actual statement. 

6. Brackets are used to indicate that a 
specification is optional and is not 
always required in the statement. 

7. Brackets enclosing stacked items 
indicate that a choice of one item 
may, but need not, be made by the 
programmer. 



8. Braces enclosing stacked items 
indicate that a choice of one item 
must be made by the programmer. 

9. All punctuation marks and special 
characters shown in the statement 
formats other than hyphens, brackets, 
braces, and underscores, must be 
punched exactly as shown. This 
includes commas, parentheses, and the 
equal sign. 

flote: Blanks may be substituted for 
commas. 

Continuation Cards: To continue either the 
program-control card or the line-control 
card, the programmer must code a nonblank 
character in column 7 2 of the continued 
card. Individual keywords and data-names 
cannot be split between cards. 

Contro l s tatement pla cement: If a main 
program is compiled with the SYMDMP option, 
or if at least one subprogram called by the 
main program is a COBOL program compiled 
with the SYMDMP option, the control cards 
may either follow or precede the 
programmers data, if any, in the input 
stream: 



//GO EXEC 

//GO. SYSDBG DD 



PGM = 

* 



[user's control cards} 



/* 
//GO.SYSIN 



DD 



{user's data cards, if any} 

/* 

For an example of the control statements 
used to compile a program with the SYMDMP 
option, see Figure 86. 

Program-Co ntrol Cards : A program-control 
card must be present at execution time for 
any program requesting a SYMDMP service. 
Program-control cards have the following 
format: 



program- id , ddname 
where: 



, ENTRY 
,NOENTRY 



, (HEX) "I 

, (NOHEX)J [,PDS] 



program-id 

is a 1- to 8-character program-name of a 
COBOL program compiled with the SYMDMP 
option. This parameter is required 
and must appear first on the 
program-control card. 

ddname 

is the execution-time ddname of the file 
that was produced at compile time on 
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SYSUT5. This parameter is required 
and must follow the program-id. 

ENTRY 

ROENTBY 

ENTEY is used to provide a trace of a 
program -name when several programs are 
link-edited together. Each time the 
program whose PROGRAM-ID matches the 
"program- id" parameter is entered, its 
name is displayed. 



HEX 
NOHEX 



PDS 



is optional and refers to the format 
of the Data Division area in the 
abnormal termination dump. If HEX is 
specified, level-01 items are provided 
in hexadecimal. Items subordinate to 
levei-01 items are printed in EBCDIC, 
if possible. Level-77 items are 
provided both in EBCDIC and 
hexadecimal. If HEX is not specified, 
items subordinate to level-01 items 
and level-77 items are provided in 
EBCDIC. If these items are 
unprintable, hexadecimal notation is 
provided. 



is optional and allows the user to 
specify that the debug file, which was 
produced at compile time on SYSUT5 and 
whose name is ddname, is a partitioned 
data set. In this case, SYMDMP 
assumes that program-id is the name of 
a member in that debug file. This 
option is intended to reduce the 
number of execution-time DD cards 
required for debug files, when many 
programs compiled with the SYMDMP 
option are executed together in a 
COBOL run-unit. Since each such 
program requires a unique debug file, 
each program- control card could 
contain a unique program- id (member) , 
the same ddname, and PDS. 

Note ; The user should be aware that 
the debug file produced at compile ' 
time contains device-dependent 
relative block addresses embedded in 
the data blocks and is, therefore, 
unmovable. The only way to alter a 
member in an existing partitioned 
debug file is through recompilation 
replacement. User attempts to 
compress the data set through IEBCOPY 
or move the data set to another data 
set through IEHMOVE will be rejected 
by these utilities. Further, the user 
should not create a partitioned data 
set from several compiler-created 
sequential debug files. SYMDMP will 
produce message IKF164I and will cancel 
debug output for any program whose 
debug file has been moved. The only 
exception is that a sequential debug, 



file can be moved to another sequential 
data set on a device of the same type. 

Lin e-Control Cards : Line-control cards 
have the following format: 

line-num[ , {verb-num) ][ ,0N •«t£# tt [ ».*]]] 



", (HEX) 1 

, (NOHEX) [„ ALL J 



, (HEX) 
, (NOHEX ) 



]. 



namel [THRU name2] 



line-num 

indicates the card numb 
with the point in the P 
Division at which the d 
to be taken. The card 
either the compiler-gen 
or, if NOM is in effect 
number in card columns 
The number must be that 
containing a section na 
name, conditional verb, 
verb. 



er associated 
rocedure 
ynamic dump is 
number is 
erated number 
, the user's 
1 through 6. 

of a card 
me, procedure 

or imperative 



verb-num 

indicates the position of the verb in 
the card indicated by "line-num" 
before whose execution a dynamic dump 
is taken. When "verb-num" is not 
specified, the value 1 is assumed; 
when specified, "verb-num" must follow 
"line-num" and may not exceed 15. 

ON n[,mC,k]3 

is eguivalent to the COBOL statement 
ON n AND EVERY m UNTIL k... This 
option limits the reguested dynamic 
dumps to specified times. For 
example, "ON n" would result in one 
dump, given the nth time "line-num" is 
reached during execution. "ON n,m" 
would result in a dump the first time 
at the nth execution of "line-num" and 
thereafter at every mth execution 
until end-of-job. K limits the number 
of dumps to the kth occurrence of 
"line-num". 



HEX 



refers to the format of the Data 
Division areas provided in the dynamic 
dump. If HEX is specified, level-01 
items are provided in hexadecimal. 
Items subordinate to level-01 items 
are printed in EBCDIC, if possible. 
Level-77 items are printed in both 
EBCDIC and hexadecimal. If HEX is not 
specified, items subordinate to 
level-01 items and level-77 items are 
provided in EBCDIC. If the items are 
unprintable, hexadecimal notation is 
provided. Note that if "namel" is 
specified and it represents a group 
item and HEX has not been specified. 
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neither the group nor the elementary 
items in the group will be provided in 
hexadecimal. 

namel [THBO name2 ] 

represents selected areas of the Data 
Division to be dumped. With the THRU 
option, a range of data-names 
appearing consecutively in the Data 
Division is dumped. "name1 M and 
«name2" may be qualified but not 
subscripted. If the programmer wishes 
to see a subscripted item, specifying 
the name of the item without the 
subscript results in a dump of every 
occurrence of that item. 



specified in the "prog ram- id H 
parameter in the preceding 
program-control card, one use of ALL 
allows the programmer to receive a 
formatted dump at normal return from 
the program. To do this, the 
programmer must ensure that the 
generated statement number of the line 
on which a STOP RON. EXIT PROGRAM, or 
60BACK statement appears is specified 
as the "line-nun" parameter. 



DEFAULT SYSPBG DATA SET 



ALL 



results in a dump of everything that 
would be dumped in the event of an 
abnormal termination for the program 



If the programmer fails to define a 
SYSDBG data set, the SYMDHP routines 
generate a default SYSDBG data set 
equivalent to the following job control 
language: 
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//SYSDBG DD * 

prog-id SYSUT5 
/* 

where: 

prog-id 

is the name of the first program 

compiled with the SYHDHP option 
encountered in the run-unit. If 
the programmer has provided a 
SYSUT5 DD statement referring to 
the file produced during the 
compilation of prog-id on SYSUT5, 
the effect of this default data 
set is to produce normal SYHDHP 
output on an abend. 

If a run-unit includes one or more 
programs that have been compiled with the 
SYHDHP option and the programmer desires to 
suppress the normal SYHDHP output on an 
abend, either of the following methods may 
be used: 

• omit the SYSUT5 DD statement from the 
execution step. This will cause the 
following message to be produced and 
SYHDHP output to be cancelled: 

IKF168I UNSUCCESSFUL OPEN OF DEBUG FILE 

• define the SYSDBG data set as 



debugging or COUNT, i.e., FLOS, STATE, 
SYHDHP or COUNT options. They must be 
executed as a logical pair only once 
per COBOL run unit. If COBOL program A 
calls COBOL program B, either A or B or 
both can be compiled with debugging, 
but only the highest level program 
compiled with debugging or COUNT 
options should contain CALL « ILBOSPIO* 
statements. The first execution of 
ILBOSPIO issues a SPIB macro 
instruction to trap the old program PSM 
in the event of a program check before 
STAE gets control at abnormal 
termination. The second execution of 
ILBOSPIO resets any previous SPIE at 
task normal termination. At abnormal 
termination, ILBODBGO will reset the 
previous SPIE. 

• Finally, any CALL ILBOSPIO 1 statements 
written in a COBOL program compiled 
without any of the above options cause 
the subroutine to return control with 
no action (SPIE is not issued) . 

If IHS will link to a COBOL load module 
many times in a job step, the ENDJOB 
compiler option should be specified. For 
additional information, see the discussion 
of the ENDJOB option in the section 
♦'Options for the Compiler" in this manual. 



//SYSDBG DD DUHHY 



This will cause the following message 
to be produced and SYHDHP to be 
cancelled: 



SAMPLE PROGRAH — TESTBUN 



IKF174I SYHDMP CANCELLED. 
CARDS FOUND. 



NO CONTROL 



SYMBOLIC DEBUGGING UNDER INFORMATION 
MANAGEMENT SYSTEM (PP5734-XX 6 P 5740- XX2) 



Execution of a COBOL program compiled with 
the options STATE, FLOW, SYHDHP, or COUNT 
under IMS requires the COBOL programmer 
to write an explicit CALL statement to 
subroutine ILBOSPIO in his source program, 
i.e., CALL 'ILBOSPIO 1 . 

• There should be one CALL statement 
written at the beginning of the 
Procedure Division and following each 
ENTRY statement in the program. 

• There should be one CALL statement 
written at each exit point in the 
program, i.e., preceding each GOBACK, 
EXIT PROGRAH or STOP RUN statement. 

• These CALL statements are effective 
only in a COBOL program compiled with 



Figure 86 contains selected portions of 
output from a program that utilizes the 
Symbolic Debugging feature. In the 
following description of the program and 
its output, letters identifying the text 
correspond to letters in the program 
listing. (SYHDMP itself provides no page 
headings or numberings on its output.) 

(A) Because the SYMDMP option is requested 
in the PARM parameter of the EXEC 
card, the logical unit SYSUT5 must be 
assigned at compile time. 

(f) The PARH parameter specifications on 
the EXEC card indicate that an 
alphabetically ordered cross-reference 
dictionary, a flow trace of 10 
procedures, and the SYHDHP option are 
being requested along with other 
options. 

© An alphabetically ordered 

cross-reference dictionary of 
data-names and procedure-names is 
produced by the compiler as a result 
of the SXREF specification in the PARH 
parameter of the EXEC card. 
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(§) The file assigned at compile time to 
SYSUT5 to store SYMDMP information is 
assigned to SYS UTS at execution time. 

(f) The SYMDMP control cards placed in the 
input stream at execution time are 
printed along with any diagnostics. 

(D The first card is the 

program-control card where: 

(a) TESTEUN is the PROGRAM-ID. 

(b) SYSUT5 is the ddname of the 
SYSUT5 file at execution time. 

(5) The second card is a line-control 
card which requests a (HEX) 
formatted dynamic dump of KOUNT, 
NAME-FIELD, NO- OF-DE PEN DENTS, and 
RECORD-NO prior to the first and 
every fourth execution of 
generated card number 70. 

Q) The third card is also a 

line-control card which reguests a 
(HEX) formatted dynamic dump of 
HOB K- RECORD and B prior to the 
execution of generated card number 
81. 

(?) The type code combinations used to 
identify data-names in abnormal 
termination and dynamic dumps are 
defined. Individual codes are 
illustrated in Figure 85. 

(5) The dynamic dumps requested by the 
first line-control card. 

(§) The dynamic dumps reguested by the 
second line-control card. 

(i) Program interrupt information is 

provided by the system when a program 
terminates abnormally. 

(j) The statement number information 

indicates the number of the verb and 
of the statement being executed at the 
time of the abnormal termination. The 
name of the program containing the 
statement is also provided. 

@ A flow trace of the last 10 procedures 
executed is provided because FLO»=10 
was specified in the PARM parameter of 
the EXEC card. 

(L) Selected areas of the Task Global 
Table are provided as part of the 
abnormal termination dump. 

(§) For each non-VSAM file- name, the 

generated card number, the file type, 
the file status (if QSAM) , the file 
organization, the DCB status, and the 
fields of the DCB and DECB, if 



applicable, are provided in 
hexadecimal. For VSAM: the card 
number, OPEN/CLOSE status, 
organization, access mode, last l/o 
operation, and file status. 

(N) The fields of records associated with 
each FD are provided in the format 
requested on the program-control card. 

* Message IKF182I appears after any 
record N that is part of a closed 
file; the status of a file is described 
in M . If the record is part of a 
closed file, the contents of the record 
are not printed; instead, the message 
appears. Message IKF182I is described 
more fully in "Appendix K: Diagnostic 
Messages" in this publication. 

(?) The contents of the fields of the 
Working-Storage section are provided in 
the format requested on the 
program-control card. 

(g) The yalue associated with each of the 
possible subscripts is provided for 
each of the data items described with 
an OCCURS clause. 

(|) Asterisks appearing within the EBCDIC 
representation of the value of a given 
field indicate that the type and the 
actual content of the field conflict. 

JL°JL&? When the SYMDMP option is used, 
level numbers appear "normalized" in the 
symbolic dump produced. For example, a 
group of data items described as: 

01 RECORDA. 

05 FIELD-A. 

10 FIELD-A1 PIC X. 
10 FIELD-A2 PIC X. 

will appear as follows in SYMDMP output: 

01 RECORDA... 

02 FIELD-A... 

03 FIELD- A1... 
03 FIELD-A2... 



Debugging TESTRUN 



Reference to the statement number 
information (3) provided by the SYMDMP 
option shows that the abnormal 
termination occurred during the 
execution of the first verb on card 
81. 

Generated card number 81 contains the 
statement COMPOTE B = B * 1. 
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Through verification of the contents 
of B at the time of the abnormal 
termination (§^ it can be seen that 
the usage of B (numeric packed) 
conflicts with the value contained in 
the data area reserved for B (numeric 
display) . 



The abnormal termination occurred 
during an attempt to perform an 
addition on a display item. 



More complex errors may reguire the use 
of dynamic dumps to isolate the problem 
area. Line-control cards are included in 
TESTRUN merely to illustrate how they are 
used and what output they produce. 



r " ' — - i 


[■"■" - ~ 


— i 


1 Code 


Meaning 




! & 


Alphabetic 




] B 


Binary 




! o 


Display 




\ E 


Edited 




1 * 


Subscripted Item 




1 F 


Floating Point 




1 N 


Numeric 




1 P 


Packed Decimal 




1 s 


Signed 




J OL 


overpunch Sign Leading 




| OT 


Overpunch Sign Trailing 




j SL 


Separate Sign Leading 




i ST 


Separate sign Trailing 





Figure 85. individual Type Codes Used in 
SYMDMP Output 
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//TtSTRUN JOB (•A*.»C*0'), , BETHKE 1550 J&3 ' ,MSGLEVEL= < 1, 1 J , CL ASS=A, 11MVS037 
// MSGCLASS=i 

***4fcTUP TAPE SCRTCH RING=YES 
•// EXEC VSCBLCLG, 

// PARM.COB=»uMAP,P«IAP,$XREF,FLOW«=10,SYMDMP, QUOTE, NORES 1 , 
// GOOMP-'SYSoUT-SS 
// SYSUTS^'aSSYiUTSiOISP^C.PASS)', 
// PARM.LKED='LISJ,LET,XREF' 

XXCVS20CLG PROC PROG-IKF CBLOO, 00001000 

XX C0BDMP=»SYS0UT*A«, 00002000 

XX iit)0MP=DUMMY, 00003000 

XX PARNCOBs'LOA'tRGNtOBBiaSKtCONOCOB^MldfLT) 1 , 00004000 

XX PARMLKD= , LJST,XRE*-,LET , ,RGNLKED=128K,C0N0LKD=M5,LT,C0BI • , 00005000 

XX PARMG0= ,, ,RGNG0*1*2K,C0NDG0=MC5,LT,C0B),<5,LT,LKED)) 1 , 00006000 

XX ^OSET='CGOSET , ,GO= , GO', 00007000 

XX il=CBLCOMPL,Vl=CBLOEV,Ul=SYSDA, 00008000 

XX *2=CBLCOMPL,V2»CBi.DEV,U2=SYSDA, 00009000 

XX i^=CBLUPM,V3=CBL0tV,J3=SYSDA, 00010000 

XX i4=CVS20LIB,V4=CBi.0EV,U*»SYSDA, 00011000 

XX 45=CVS20LIB,V5*CBc0EVfU5=SYS0A, 00012000 

XX S6=CVS20LIB,V6=CBcDfcV,U6=SYSDA, 00013000 

XX ,>7=CVS20LIB,V7=CBi.DEV,U7»SYSDA, 00014000 

XX i8=CVS20LIB,V8=CBt0tVtU8«SYS0A, 00015000 

XX i9=CVS20LIB,V9=«ScR=CBLDEV , ,U9=SYSDA, 00016000 

XX il0= , SYSl.LINKLIB«,V10=,U10= 00017000 

XXCJB EXEC PGM=£PR0G,REGI0N=6RGNC0B,C0ND*6C0NDC0B, 00027000 

XX PARM=«L0A > N0LIB,S4ZE*128K>BUFsl2KtPMA,0MA.SXRt0PT,RESfGPARHC0B > 00028000 

XXSFEPLIB 00 DSN=6Sl,V0L=SER«6Vl,UNU=&Ul,0ISP=SHR 00029000 

XX 00 0SN=6S2, VOL*SER*eV2,UNIT=£U2,DISP=SHR 00030000 

XX 00 DSN=SS3,V0L=SER=6V3,UNIT=SU3,DISP=SHR 00031000 
//CuB.SYSPRINT 00 iYSOUT=S 

X/SYSPRINT DO SYSOUT=A 00032000 

XXSYSUOUMP 00 6C0B0MP 00033000 

XXSYSUT1 00 UNIT=SYSoA,iPACE=(TRK,(25,3)),0SN=£iSYSjri 00034000 

XXSYSUT2 00 UNIT=SYSuA,SPA:E*(TRKf(25,3)J,0SN=6SYSUT2 00035000 

XXSYSUT3 00 UNIT=SYSuA,SPACE=(TRK,(25,3)),DSN=£SYSUT3 00036000 

XXSYSUT4 00 UNIT=SYSuA,SPACE*(TRK,(25,3)),DSN=ESYSUT4 00037000 

XXSYSUT5 00 UNIT=SYSJA,SPA;E=CTRK,{25,3)) ,0SN*6SYSUT5 00338000 

XXSYSUT6 00 UNIT*SYSuA,$PACE*<TRK,(25,3)),DSN=6SYSUT6 00039000 

XXSYSLIN 00 OSNAME=£i.tiAOSET,OISP=( MOD, PASS), UNIT=SYSDA, 00040000 

XX iPACE=(80,(500,10w»)i 00041000 
//CJB.SYSIN 00 * 



Figure 86. Osing the SYMDHP Option to Debug the Program TEST80N (Part 1 of 11) 
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00001 
00002 
00003 
00004 
00005 
00006 
00007 
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00021 
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00023 
00024 
00025 
00026 
00027 
00028 
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00033 
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00035 
00036 
00037 
00038 
00039 
00040 
00041 
00042 
00043 
00044 
00045 
00046 
00047 
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00049 
00050 
00051 
00052 
00053 
00054 
00055 
00056 
00057 



100010 IDENTIFICATION DIVISION." 

10002.0 PROGRAM-ID. TESTRUN. 

100030 AUTHOR. PROGRAMMER NAME. 

100040 INSTALLATION. NEW YORK PROGRAMMING CENTER. 

100050 DATE-WRITTEN. JULY 12, 1968. 

100060 DATE-COMPILED. JUN 11,1974. 

.100070 REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 

100080 COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK AS 

100090 INPUT. 

100100 ENVIRONMENT DIVISION. 

100110 CONFIGURATION SECTION. 

100120 SOURCE-COMPUTER. IBM-360-H50. 

100130 OBJECT-COMPUTER. IBM-360-H50. 

100140 INPUT-OUTPUT SECTION. 

100150 FILE-CONTROL. 

100160 SELECT FILE-1 ASSIGN TO UT-2400-S-SAMPLE. 

100170 SELECT FILE-2 ASSIGN TO UT-2400-S- SAMPLE. 

100180 DATA DIVISION. 

100190 FILE SECTION. 

100200 FD FILE-1 

100210 LABEL RECORDS ARE OMITTED 

100220 BLOCK CONTAINS 100 CHARACTERS 

100225 RECORD CONTAINS 20 CHARACTERS 

100230 RECORDING MODE IS F 

100240 DATA RECORD IS RECORD- 1. 

100250 01 RECORD-1. 

100260 02 FIELD-A PICTURE IS X(20). 

100270 FD FILE-2 

10028 LABEL RECORDS ARE OMITTED 

100290 BLOCK CONTAINS 5 RECORDS 

100300 RECORD CONTAINS 20 CHARACTERS 

100310 RECORDING MODE IS F 

100320 DATA RECORD IS RECORD-2. 

100330 01 RECORD-2. 

100340 02 FIELD-A PICTURE IS X(20). 

100350 WORKING- STORAGE SECTION. 

100360 77 KOUNT PICTURE S99 COMP SYNC. 

10037 77 NOMBER PICTURE S99 COMP SYNC. 

100375 01 FILLER. 

100380 02 ALPHABET PICTURE X(26) VALUE "ABCDEFGHIJXLMNOPQRSTUVWXYZ". 

100395 02 ALPHA REDEFINES ALPHABET PICTURE X OCCURS 26 TIMES. 

100405 02 DEPENDENTS PICTURE X(26) VALUE "0123401234012340123401234 

100410- "0". 

100420 02 .DEPEND REDEFINES DEPENDENTS PICTURE X OCCURS 26 TIMES. 

100440 01 WORK-RECORD. 

100450 02 NAME-FIELD PICTURE X. 

100460 02 FILLER PICTURE X VALUE IS SPACE. 

10047 02 RECORD-NO PICTURE 9999. 

100480 02 FILLER PICTURE X VALUE IS SPACE. 

100490 02 LOCATION PICTURE AAA VALUE IS "NYC". 

100500 02 FILLER PICTURE X VALUE IS SPACE. 

100510 02 NO-OF-DEPENDENTS PICTURE XX. 

100520 02 FILLER PICTURE X(7) VALUE IS SPACES. 

100 521 01 RECORDA. 
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00058 


100522 


00059 


100523 


00060 


100530 


00061 


100540 


00062 


100550 


00063 


100560 


00064 


100570 


00065 


100580 


00066 


100590 


00067 


100600 


00068 


100610 


00069 


100620 


00070 


100630 


00071 


100640 


00072 


100650 


00073 


100660 


00074 


100670 


00075 


100680 


00076 


100690 


00077 


100700 


00078 


100710 


00079 


100720 


00080 


100730 


00081 


100731 


00082 


100740 


00083 


100750 


00084 


100760 


00085 


100770 


00086 


100780 



02 A PICTURE S9(4) VALUE 1234. 

02 B REDEFINES A PICTURE S9(7) COMPUTATIONAL- 3. 
PROCEDURE DIVISION. 
BEGIN. 

NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 

AND INITIALIZES COUNTERS. 
STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT NOMBER. 

NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE 

CONTAINED IN THE FILE, WRITES THEM ON TAPE, AND DISPLAYS 

THEM ON THE CONSOLE. 
STEP-2. ADD 1 TO KOUNT, ADD 1 TO NOMBER, MOVE ALPHA (KOUNT) TO 

NAME-FIELD. 

MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS. 

MOVE NOMBER TO RECORD- NO. 
STEP-3. DISPLAY WORK-RECORD UPON CONSOLE. WRITE RECORD-1 FROM 

WORK-RECORD. 
STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26. 

NOTE THAT THE FOLLOWING CLOSES OUTPUT AND REOPENS IT AS 

INPUT. 
STEP- 5. CLOSE FILE-1. OPEN INPUT FILE- 2. 

NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES OUT 

EMPLOYEES WITH NO DEPENDENTS. 
STEP- 6- READ FILE- 2 RECORD INTO WORK-RECORD AT END GO TO STEP- 8. 

COMPUTE B = B + 1. 
STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "Z" TO 

NO-OF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO 

STEP- 6. 
STEP- 8. CLOSE FILE- 2. 

STOP RUN. 



<£> 



■*■ CROSS-REFERENCE DICTIONARY 



DATA NAMES 



REFERENCE 



A 

ALPHA 

ALPHABET 

B 

DEPEND 

DEPENDENTS 

FIELD-A 

FIELD-A 

FILE-1 

FILE-2 

KOUNT 

LOCATION 

NAME-FIELD 

NO-OF-DEPENDENTS 

NOMBER 

RECORD-NO 

RECORD-1 

RECORD- 2 

RECORDA 

WORK-RECORD 



000058 
000044 
000043 
000059 
000047 
000045 
000029 
000037 
000017 
000018 
000040 
000053 
000049 
000055 
000041 
000051 
000028 
000036 
000057 
000048 



000068 



000081 
000070 



000064. 000072 000077 
000077 000080 000085 
000064 000068 000070 000074 

000068 

000070 000082 

000064 0000b8 000071 

000071 

000072 

000080 

000072 000080 000083 
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PROCEDURE NAMES 



REFERENCE 



BEGIN 
STEP-1 
STEP- 2 
STEP- 3 
STEP- 4 
STEP- 5 
STEP- 6 
STEP-7 
STEP- 8 



000061 
000064 
000068 
000072 
000074 
000077 
000080 
000082 
000085 



000074 
000074 



000083 



000080 



ERROR MESSAGE 



14 
58 



IKF1183I-W 
IKF2190I-W 



IBM- 370 IS ONLY VALID COMPUTER-NAME. IBM-360 SPECIFICATION IGNORED. 
PICTURE CLAUSE IS SIGNED, VALUE CLAUSE UNSIGNED. ASSUMED POSITIVE. 



IEC130I SYSLIB DD STATEMENT MISSING 
IEF142I - STEP WAS EXECUTED - COND CODE 0004 

VSCBL1.LMOD KEPT 

VOL SER NOS= DB143 . 

SYS74162.T203933.RV0O0.TESTRUN.R0000O11 DELETED 
VOL SER NOS= 2314 00. 

SYS74162.T20393 3.RV000.TESTRUN.R0000012 DELETED 
VOL SER NOS= 333001. 

SYS7416 2.T203933.RV000.TESTRUN.R0000013 DELETED 
VOL SER NOS= 333001. 

SYS7 416 2. T20 39 3 3. RV000.TESTRtJN.R0 00001 4 DELETED 
VOL SER NOS= 231400. 

SYS74162.T203933.RV000.TESTRUN.SYMDBG PASSED 
VOL SER NOS= 333001. 

SYS7 416 2.T203933.RV000.TESTRUN.R0000015 DELETED 
VOL SER NOS= 231400. 

SYS7416 2.T20393 3.RV000.TESTRUN.LKEDINP PASSED 
VOL SER NOS= 333001. 

SYS74 16 2. T20393 3.SV000.TESTRUN.R0 00001 6 DELETED 
VOL SER NOS= 333001. 

SYS7416 2.T203933.SVOOO.TESTRUN.R0000017 SYSOUT 
VOL SER NOS= 231400. 

SYS7416 2.T20393 3.RV0C0.TESTRUN.S0000018 SYSIN 
VOL SER NOS= 2314 00. 

SYS74162.T203933.RVOOO.TESTRUN.S0000018 DELETED 
VOL SER NOS= 231400. 
IEF373I STEP /COB / START 74162.2054 

IEF374I STEP /COB / STOP 74162.2058 CPU 0MIN 12.17SEC STOR VIRT 1 
XXLKED EXEC PGM=1EWL,PARM=' XREF, LIST, LET' , COND= ( 5, LT, COB) , REGION=128K 
DD DSN=VSCBL1.LIB,DISP=SHR,UNIT=2314,V0L=SER=DB143 
DD DSN=6LKEDINP,DISP= (OLD, DELETE) 
DD DDNAME=SYSIN 

DD SPACE=(1G24, (50,20)) ,UNIT=( 2314, SEP=SYSL1N) 

DD DSN=6LMODLIB(MBRNAME) , UNIT= ( 2314 ,SEP= (SYSLIN, SYSUT1) ) , * 
DISP= (MOD, PASS) ,SPACE=(102 4, (50,20,1)) 
//LKED.SYSPRINT DD SYSOUT=G 
X/SYSPRINT DD SYSOUT=A 
IEF236I ALLOC. FOR TESTRUN LKED 
IEF237I 233 ALLOCATED TO SYSLIB 
ALLOCATED TO SYSLIN 
ALLOCATED TO SYSUT1 
ALLOCATED TO SYSLMOD 
ALLOCATED TO SYSPRINT 



IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 
IEF285I 



XXSYSLIB 

XXSYSLIN 

XX 

XXSYSUT1 

XXSYSLMOD 

XX 



IEF237I 250 
IEF237I 234 
IEF237I 235 
IEF237I 230 



28K 

00800190 

00800200 

00800210 

0080022C 

00800230 

00800240 

00800250 

00800260 
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XXSYSLIB OD DSN=SS4,i/0L=SER=SV4,UNIT=e,U4,DISP=SHR 00047000 

XX JD 0SN=SS5tV0L=S£K=6»/5,JNIT=GU5,0ISP=SHR 00048000 

XX JD DSN=6S9,V0L=«>Vy,UNIT=&U9,DISP=SHR 00049000 

XXSYSUU OD UNIT=(SYiDA,SEP=(SYSLIN,SYSLMOD)),SPACE=(1024 t (50,20)J 00050000 
//LKED.SYSPRINT 00 SYSOUT=S 

X/SYSPRINT DD SYSOUT=A 00051000 

XXGJ EXEC PGM=*.LKED.SlfSLM00.PARM= , 6PARMG0 , fRE6I0N=£RGN60,CDND=6:0N030 00052000 
XXSTEPLIB 00 DSN=£S6,V0L=SER=£V6,UNIT=£U6,DISP=SHR 00053000 

XX JD DSN=SS8,V0L=SEk=£V8,UNIT=£U8,DISP=SHR 00054000 

XX JO DSN=£S7,VOL=SEK=£V7,UNIT=£U7,DISP=SHR 00055000 

XX JO DSN=£S10,V0L=£V10,UNIT=£U10,DISP=SHR 00056000 

//GU.SYSOUT DO SYSuUT=S 

X/SYSOUT DD SYSOUT=A 00057000 

XXSYSUOUMP DD 6G0DMP 00058000 

-^ //GJ.SYSDBOUT DO SYSOUT=S 

( D)*-//GJ.SYSUT5 OD DSN=£&SYSUT5,DISP = ( OLD, PASS) 

V --^ / //Gd. SAMPLE 00 UNir = 2400,LABEL=(,NL),DISP = (NEW, DELETE) 
//GJ.SYSOBG DO * 
// 
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G>- 



SYMOMP CONTROL CARDS 



(?)-»- TESTRuN.SYSUT 5 

(J)— »-70,ON 1,4, (HEX), KOUNT, NAME-FIELD, NO-OF-DEPENDENTS, RECORD-NO 

Q)-*- 81 1 (HEX) , WORK-RECORD, B 



NO ERRORS FOUND IN CONTROL CARDS 



©^ 



cODfc 

A 

AN 

ANfc 

D 

Ot 

F 

FD 

Nb 

NB-S 

ND 

ND-OL 

ND-OT 

ND-SL 

ND-ST 

NE 

NP 

NP-S 



(¥)-»- J ES7RUN AT CARD 000070 
LOC CARD LV NAME 

015758 000040 77 KOUNT 



C157S8 00004* 02 NAME-FIELD 
0157A3 00005a 02 NO-OF-DEPENuENTS 

07579A 000051 02 RECORD-NO 



TYPE CODES USED IN SVMOMP OUTPUT 

MEANING 

ALPHABETIC 

ALPHANUMERIC 

ALPHANUMERIC EOITED 

DISPLAY (STERLING NONREPORT) 

OISPLAY EDITED (STERLING REPORT) 

FLOATING POINT (COMP-l/COMP-2) 

FLOATING POINT DISPLAY (EXTERNAL FLOATING POINT) 

NUMERIC BINARY UNSIGNED (COMP) 

NUMERIC BINARY SIGNED 

NUMERIC DISPLAY UNSIGNED (EXTERNAL DECIMAL) 

NUMERIC DISPLAY OVERPUNCH SIGN LEADING 

NUMERIC OISPLAY OVERPUNCH SIGN TRAILING 

NUMERIC DISPLAY SEPARATE SIGN LEADING 

NUMERIC DISPLAY SEPARATE SIGN TRAILING 

NUMERIC EDITED 

NUMERIC PACKEO DECIMAL UNSIGNED (COMP-3) 

NUMERIC PACKEO DECIMAL SIGNED 

SUBSCRIPTED 



(HEX) 



(HEX) 



(HEX) 



TYPE 


VALUE 


NB-S 


+01 




0001 


AN 


A 


AN 


** 




0000 


ND 


**** 




00000000 



TESTRUN AT CARD 000070 



LCC CARD LV NAME 

CI 5758 C0004J 77 KOUNT 

075798 00004* 02 NAME-FIELD 

C15 7AJ 0C0C53 02 NO-OF-DEPENuENTS 

C7 57SA 000051 02 RECORC-NO 



(HEX) 



TYPE 


VALUI 


NB-S 


+05 




0005 


AN 


E 


AN 


3 


ND 


0004 
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TESTRUN AT CaRO 000070 
LCC CARO LV NAME 

07535ti CC004u 77 KOUNT 

CIS 798 00004* 02 NAME-FIELD 

C75 7AJ 00005a 02 NO-OF-DEPENuENTS 

C7S7SA 00005a 02 RECORC-NO 



(HEX) 



TYPE 


VALUI 


NB-S 


+09 




0009 


AN 


I 


AN 


2 


NO 


0008 



TESTRUN AT CaRD 000070 
LCC CARD LV NAME 

CI 5158 00004U 77 KOUNT 

CI 5 798 000049 02 NAME-FIELD 

C15 7A3 00005a 02 NO-GF-D£PENuENTS 

C75 79A 00005* 02 RECCRD-NO 



(HEX) 



TYPE 


VALUI 


NB-S 


+ 13 




OOOD 


AN 


M 


AN 


1 


NO 


0012 



TESTRUN AT CaRD 000070 
LCC CARD LV NAME 

C 15758 00004J 77 KOUNT 

01579d 00004V 02 NAME- FIELD 

015 7A3 00005a 02 NO-OF-DEPENuENTS 

C1579A 00005a 02 RECORD-NO 



(HEX) 



TYPE 


VALU 


NB-S 


+ 17 




0011 


AN 


Q 


AN 





NO 


0016 



IcSTRUN AT CARD 000070 
LCC CARD LV NAME 

015758 00004u 77 KOUNT 

C7J798 00004V 02 NAME-FIELD 
0157A3 000053 02 NO-OF-DEPENuENTS 
C1579A 00005a 02 RECORD-NO 



(HEX) 



TYPE 


VALUI 


NB-S 


+ 21 




0015 


AN 


U 


AN 


4 


NO 


0020 



TESTRUN AT CARD 00007C 
LCC CARD LV NAME 

CI 5158 00004J 77 KOUNT 

C157S8 00004ai 02 NAME-FIELD 
C157A3 00005a 02 NO-OF-DEPENuENTS 
01579a 00005a 02 RECORD-NO 



(HEX) 



NB-S 


+25 




0019 


AN 


Y 


AN 


3 


ND 


0024 



<s>- 



TESTRUN 


AT CARD 000081 


LCC 


CARD 


LV 


NAME 




000040 


01 


WCRK-RECORO 


C15798 








C157S8 


00004V 


02 


NAME-FIELD 


015799 


00005u 


02 


FILLER 


01579A 


000051 


02 


RECORD-NO 


01579E 


00005*: 


02 


FILLER 


C157SF 


00005j 


02 


LOCATION 


C157A2 


000054 


02 


FILLER 


C 1 5 7A3 


00005a 


02 


NO-OF-DEPENuENTS 


0151A5 


00005c 


02 


FILLER 



C157eO 000059 02 B 



TYPE VALUE 
(HEX) C140F0F0 F0F140D5 E8C340F0 40404040 40404040 



(HEX) 



AN 




ND 


0001 


AN 




A 


NYC 


AN 




AN 





AN 




NP-S 


*1*2*3* 




F1F2F3C4 
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COBOL ABEND DIAGNOSTIC AIDS 



PfCGRAM TESTRUN 

(I J— "-LAST PSW BEFOKe ABEND = FF8500U7E0075F46 SYSTEM COMPLETION COOE = OC7 



(jj— "-LAST CARO 



NUMoER/VERB NUMBER EXECUTED — CARD NUMBER 000081/VERB NUMBER 01. 



FLOW TRACE 
TESTRUN OOOOod 000072 000068 U00072 000068 000072 000068 000072 000077 000080 



DATA DIVISION DUMP OF TESTRUN 



(T)— "-TASK GLOBAL TABLE LOC 



SAVt AREA 


07590u 


0030C4C2 


0O074FB0 


00074B90 


50075F24 


6001FC3C 


40075F3C 


0007AA70 


00075900 




0759FU 


0000001A 


000758C8 


00075668 


00075758 


0007AA1C 


000 7A A 70 


00076082 


000756B8 




Q75Alu 


00076176 


00075C18 














JUTCH 


075Alo 


3D02804B 
















TALLY 


075A1C 


00000000 
















SCRT SAVE 


75A24/ 


00000000 
















ENTRY-SAVE 


75A24 


00075C9C 
















SORT CORE SUE 


075A2d 


00000000 
















SET CODE 


075A2o 


0000 
















SCRT RET 


075A2c 


0000 
















t«OPKING CELlS 


075A3U 


04400000 


50075F24 


12D474E8 


0007AC10 


00075900 


00075900 


OOOOOOIA 


000758C8 




075A5O 


000756B8 


00075758 


0007AA1C 


0007BFE8 


00076082 


000756B8 


00075C9C 


00075C18 




075A7u 


50077EF0 


46075F36 


0007AC10 


80075900 


000757F4 


0000001A 


08FOFOOO 


00000000 




075A9U 


00000000 


58B0D1D8 


F870D210 


C0560700 


5B20D1A8 


07F20000 


000009C8 


00074EDO 




075ABU 


20000000 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


0007509E 




075A0i> 


00000000 


01000000 


00075D8C 


00076F6A 


60075D48 


00075DA0 


00000000 


OOOOOOIA 




075AFU 


00075793 


500760E6 


00018C80 


0007795A 


0007596 


80075900 


00075900 


OOOOOOIA 




075Blu 


000 75 8C 8 


000756B8 


00075758 


0007AA1C 


00000000 


00076082 


000756B8 


00075C9C 




075 B3u 


00075C18 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 




075B5O 


00000000 


00000000 


00000000 


00000000 










SCRT FILE SHE 


075B6U 


OCOOOOOO 
















SORT MODE SiZE 


075664 


00000000 
















PGT-VN TBL 


075B6o 


00000000 
















IGT-VN TBL 


07566C 


00000000 
















FESERVED 


075B7o 


00000000 
















LENGTH OF Vn TBL 


075B7* 


0000 
















LABEL RET 


075B7O 


00 
















RESERVED 


07567/ 


00 
















CBG R14SAVE 


075B7O 


400 75F3C 
















COBOL INDICATOR 


075B7c 


6007839C 
















A( INIT1J 


075B8U 


000756B8 
















CEEUG TABLE PTR 


075B8* 


00000558 
















SLBCOM ADDR 


075B80 


00078D98 
















SCRT-MESSAGc 


075B8C 


SYSOUT 
















SY50UT DCNArtE 


07589* 


E3 
















FESERVED 


07589S 


80 
















CCBCL ID 


075B9o 


OOOC 
















CCMPILED POiNTER 


075B90 


00075740 
















COUNT TABLE ADDRESS 


075B91. 


00000000 
















FESERVED 


075 BAo 


00000000 


00000000 














CBG R11SAVE 


075BAo 


00075C9C 
















CCUNT CHAIN ADDRESS 


75BAC 


00000000 
















FREL1 CELL PTR 


075BBO 


00075C98 
















UNLSED 


07568* 


00000000 


00 














TA LENGTH 


07586^ 


000 000 
















FESERVED 


075BBC 


00000000 


00000000 














PCS LIT PTR 


075BC* 


00000000 
















CEEUGGING 


075BCo 


00000000 
















CC FOR INITiAL INPUT 


075BCL 


00000000 
















CVERFLOW CEcLS 


(NONEi 


















EL CELLS 


075 BDU 


000 756B8 


0007AA70 


00075758 












CtCBADR CELlS 


(NONEI 


















fie CELLS 


075BDC 


00000000 
















CEBUG TRANSFER 


(NONEi 


















CEEUG CARD 


( NONE J 


















CEEUG BLL 


(NONEi 


















CEBUG VLC 


(NONE) 


















CEBUG MAX 


(NONE) 


















PESERVED 


(NONEi 


















CEBUG PTR 


(NONEi 


















TEMP STORAGE 


075BEU 


00000000 


0000001C 














ELL CELLS 


075BEO 


00000000 


00000000 














VLC CELLS 


(NONEi 


















SBL CELLS 


(NONEi 


















INDEX CELLS 


(NONEJ 


















CTHER (SEE MEMORY MAP) 


075BFu 
075C1U 


00075779 
0A0O098A 


00075793 
15130000 


00075DF6 


00075DF6 


00000000 


80075900 


00000000 


00000000 



LPSI=OC0COOuO 
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DATA DIVISION DUMP OF TESTRUN 



LCC 



®r 



CARD 
■*- 000017 



LV NAME 
FD FILE-1 



TYPE 

QSAM 



VALUE 



C757F4 

C7f 614 
C 7 5834 



FILE: CLOSED ORGANIZATION: PHYSICAL SEQUENTIAL 
LAST SUCCESSFUL I/O STMT: CLOSE FILE STATUS: 00 
DCB 00000000 00000000 00000000 00000006 00830000 0007AA01 00004000 000000 
46000001 000757BC E2C1D407 D3C54040 02000048 00000001 08000001 OOOOOC 
00000000 00000001 00000001 00000001 00000014 00000001 00000000 000000 



® 



00002(i 01 RECCRD-1 
IKF182I UNINITIALIZED OR INVALID BASE AODRESS FOR DATA ITEM ABOVE. 

»-00C02* 02 FIELD-A AN 

IKF182I UNINITIALIZED OR INVALID BASE ADDRESS FOR DATA ITEM ABOVE. 



) 


-OOCOld 


FD 


FILE-2 




(35900 










C75920 










CI 5940 










L 


000036 


01 


RECORD-2 


^C7AA7G 


000037 


02 


FIELD-A 




)-*-C7 57 5tt 


000040 


77 


KOUNT 




C 7 5 1 5A 


CC004i 


77 


NCMBER 






00004^ 


01 


FILLER 




C75760 


00004.* 


02 


ALPHABET 




000044 


02 


ALPHA 










(SUB1J 


V- ^015760 








1 


075761 








2 


7 57 62 








3 


C7 576J 








4 


075764 








5 


CI 57 65 








6 


C 7 5766 








7 


C75767 








8 


075768 








9 


C7S769 








10 


07 576A 








11 


07576B 








12 


C7576C 








13 


C7576D 








14 


C7576t 








15 


C7 576F 








16 


075770 








17 


C75771 








18 


0157 72 








19 


C 7 57 73 








20 


C75774 








21 



QSAM FILE: OPEN ORGANIZATION: PHYSICAL SEQUENTIAL 

LAST SUCCESSFUL I/O STMT: READ FILE STATUS: 00 
DCB 00000000 00000000 00000000 00000005 0083C300 0507AA00 00004000 0007A8 
46077F8C 900758C8 OOCC4800 007DC414 12D474EP 00BE1018 07000001 OOODOO 
20202020 0007A920 0007AAD4 0007AA70 00000014 00000001 00000000 00BD6A 



AN 

NB-S 

NB-S 



AN 
*AN 



A 0001 NYC 

+26 

+26 



ABCDEFGHIJKLKNOPQRSTUVWXYZ 
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DATA DIVISION DUMP OF TESTRUN 



LCC 


CARD 


LV 


NAME 




075775 








22 


C75776 








23 


C15777 








24 


C35778 








25 


CI 5779 








26 


07577A 


000045 


02 


DEPENDENTS 




000047 


02 


DEPEND 










(SUBU~*—(l 


(7577A 








1 v 


C7 577B 








2 


07577C 








3 


C7577D 








4 


C7577E 








5 


C7577F 








6 


C7J780 








7 


C75761 








8 


C75782 








9 


C757£i 








10 


C757£4 








11 


075785 








12 


C757£6 








13 


075767 








14 


Ci57fcfl 








15 


C35769 








16 


C7578A 








17 


C7 578B 








18 


Q7578C 








19 


07578D 








20 


C757CE 








21 


07578F 








22 


C557SO 








23 


0*5751 








24 


C757S2 








25 


£7 5793 








26 




000046 


Oi 


WORK-RECORD -«— (P 


C75798 


000049 


02 


NAME-FIELD V ~ 


C757SS 


0COO5U 


02 


FILLER 




Q757SA 


00005a 


02 


RECORD- NO 


C157SE 


00005^ 


02 


FILLER 




C57SF 


00005.* 


02 


LOCATION 


C757A2 


00005* 


02 


FILLER 




7 5 7A3 


000055 


02 


NO-OF-DEPENoENTS 


C7 57A5 


00005o 


02 


FILLER 






000057 


01 


RECORCA 




C757BC 


0C0O56 


02 


A 




C 7 5780 


00005* 


02 


B 




LGC 


CARD 


LV 


NAME 





TYPE 



AN 
♦ AN 



AN 

AN 

ND 

AN 

A 

AN 

AN 

AN 



VALUE 

V 
W 
X 
Y 
Z 
01234012340123401234012340 



A 

0001 
NYC 




ND-OT +1234 
NP-S *1*2*3* 

(HEX) F1F2F3C4 



r® 



TYPE VALUE 
END OF COBOL DIAGNOSTIC AIDS 



Figure 86. Using the SYHDMP Option to Debug the Program TESTRUN (Part 10 of 11) 
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IEC130I SYSDTERM DD STATEMENT MISSING 

A 0001 NYC 

B 0002 NYC 1 

C 0003 NYC 2 

D 0004 NYC 3 

E 0005 NYC 4 

F 0006 NYC 

G 0007 NYC 1 

H 0008 NYC 2 

I 0009 NYC 3 

J 0010 NYC 4 

K 0011 NYC 

L 0012 NYC 1 

M 0013 NYC 2 

N 0014 NYC 3 

0015 NYC 4 

P 0016 NYC 

Q 0017 NYC 1 

R 0018 NYC 2 

S 0019 NYC 3 

T 0020 NYC 4 

U 0021 NYC 

V 0022 NYC 1 
W 0023 NYC 2 
X 0024 NYC 3 

Y 0025 NYC 4 
Z 0026 NYC 

COMPLETION CODE - SYSTEM=0C7 USER=0000 

IEF285I SYS74162.T203933.RV000.TESTRUN.LMODLIB PASSED 

IEF285I VOL SER NOS= DC151 . 

IEF285I VSCBL1.LIB KEPT 

IEF285I VOL SER NOS= DB143 - 

IEF285I SYS74162.T203933.RV000.TESTRUN.SYMDBG DELETED 

IEF285I VOL SER NOS= 333001. 

IEF285I SYS74162.T203933.SVOOO.TESTRUN.R0000021 SYSOUT 

IEF285I VOL SER NOS= 231400. 

IEF285I SYS74162.T203933.SV000.TESTRUN.R0000022 SYSOUT 

IEF285I VOL SER NOS= 333001. 

IEF285I SYS74162.T203933.SV000.TESTRUN.R0000023 DELETED 

IEF285I VOL SER NOS= 333001. 

IEF285I SYS74162.T203933.SVOOO.TESTRUN.R0000024 DELETED 

IEF285I VOL SER NOS= 231400. 

IEF285I SYS74162.T203933.RV000. TESTRUN. R0000025 DELETED 

IEF285I VOL SER NOS= L00001. 

IEF285I SYS74162.T203933. RV000. TESTRUN. S0000026 SYSIN 

IEF28 5I VOL SER NOS= 2314 00. 

IEF285I SYS74162.T203933.RV000.TESTRUN.S0000026 DELETED 

IEF285I VOL SER NOS= 231400. 

IEF373I STEP /GO / START 74162.2059 

IEF374I STEP /GO / STOP 74162.2105 CPU 0MIN 09.72SEC STOR VIRT 64K 

IEF285I SYS74162.T203933.RV000.TESTRUN.LMODLIB DELETED 

IEF285I VOL SER NOS= DC151 . 

W5F375I JOB /TESTRUN / START 74162.2054 

IEF376I JOB /TESTRUN / STOP 74162.2105 CPU 0MIN 24.96SEC 



Figure 86. Using the SYHDMP Option to Debug the Program TESTHUN (Part 11 of 11) 
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messages, an 
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ut" shows th 
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program. 



editor, COBOL load 
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rm of printed 
ecJcs, diagnostic or 
d data sets 

storage devices, 
he output listings 
ment and debug 
of the output 

program is used 
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e listing generated 



COMPILER,,, OUTPUT 

The output of the compilation job step 
may include: 

* A printed listing of the job control 
statements 

* Device allocation and deallocation 
messages from the job scheduler 

* A printed listing of the statements 
contained in the source module 

* A glossary of compiler-generated 
information about data 

* A printed listing of the object code 

* Compiler diagnostic messages 

* System messages 



• Disposition messages from the job 
scheduler 

• An object module 

• A cross-reference listing 

• A condensed listing containing source 
card numbers and the location of the 
generated instruction for each verb 

• Compiler statistics 

• Reformatted source code, either with or 
without a compilation, through the 
lister feature of the OS/VS COBOL 
Compiler. For details, see the chapter 
"Lister Feature." 

Diagnostic messages associated with the 
compilation of the source program are 
automatically generated as output. The 
other forms of output may be reguested in 
the PAHM parameter in the EXEC statement. 
The level of diagnostic messages printed 
depends upon the FLAGS or FLAGE options. 

All output to be listed is written on 
the device specified by the SYSPEINT DD 
statement. Line spacing of the source 
listing and the number of lines per page 
can be controlled by the SPACEn and LINECNT 
options. 

Figure 87 contains a portion of the 
compiler output listing shown in "Appendix 
A: Sample Program Output. " Each type of 
output is numbered, and each format within 
each type is lettered. The text following 
Figure 87 is an explanation of the 
illustration. 
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//TcSTRUN JOB < ' A=aC40 • ) , ' BETHKE 1550 J63 * ,MSGLEVEL=< I , 1 ) ,CLASS=Ai 

// MSGCLASS=i 

***jETUP TAPE SCRTCH RING=YES 

// EXEC CVS20CLG, 

// PARM.COB= , uMAP,PMAP,SXREF,FLOW'=10,SyMDMP,QU0TE,N3RES', 

// G0DMP='SYSuUT=S», 

// SySUT5='66iSYiUr5,DISP=(,PASS) ', 

// PARM.LKED^LISfTLET.XREF' 

/XCVS20CLG PROC PROG= KFCBLOO, 

XX cOBDMP=«SYSOUT=A' , 

XX uUDMP=DUMMY, 

XX PARMCOB='LOA« ,RGMcOb=128K f CONDCOB=M 16.LT) • , 

XX PARMLK0= , LIST,XREr,LtT«,RGNLKED=128K,C0NDLKD=M5,LT,C3B) ', 

XX PARMG0=« ',RGNG0=1<*2K,C0NDG0='((5,LT,C0B) , ( 5 ,LT,LKEO) ) • , 

XX G0SET='£G0SET' .GO^'GO 1 , 

XX il=C8LC0MPL,Vl=CbLDEV,Ul=SYSDA, 

XX 52=CBLC0MPL,V2=C8L0EV,U2=SYSDA, 

XX j3=CBLUPM,V3=CBLDcV,U3=SYSDA, 

XX S4=CVS20LIB,V4=CBlDEV,U4=SYSDA, 

XX o5=CVS20LIBiV5=C8LDfcVtU5=SYS0A, 

XX o6=CVS2 0LIB,V6=CBlDEV,U6=SYS0A, 

XX i7=CVS20LIB,V7=CBL0EV,U7=SYSDA, 

XX i8=CVS2 0LIB,V8=CB».DtV,U8 = SYS0A, 

XX i9=CVS20LIB f V9='ScR=:BLDEV , ,U9=SYSDA, 

XX j10='SYS1.LINKLIB' ,ViO=,J10= 

XXCuB EXEC PGM=£PR0G,RESI0N=£RSNC0B,COND=£C0NDCOB, 

XX PARM=» L0A,N0LIB,$iZE = 128K,BJF=12K,P»^A t D^1A,SXR,DPT,RES,ePAR>C0B , 

XXSTEPLIB DO 0SN=£S1, V0L=SER=£V1 ,UNIT=£U1 ,DISP=SHR 

XX DO DSN=£S2,V0L=SER=£V2,UNIT=£U2,DISP=SHR 

XX OD bSN=6S3,VGL=SER=£V3,UNIT=£U3,DISP=SHR 

//CuB.SYSPRINT OD oYSOUT=S 

X/SYSPRINT DD SYSOUI=A 

XXSYSUDUMP 00 SCOBDMP 

XXSVSUT1 00 UNIT=SYSi>A, SPACE=( TRK, ( 25,3) ) ,3SN=£SYSUT1 

XXSVSUT2 DD UNIT=SYSuA,S PACE= (TRK, ( 25 , 3) ) , DSN=£SYSUT2 

XXSYSUT3 OD UNIT=SYSuA, SPACE=( TRK, ( 25 ,3 ) ) ,DSN=£SYSUT3 

XXSYSUT4 DD UNIT = SYSl*A, SPACE=( TRK, ( 25, 3) ) ,3SN=£SYSUT4 

XXSYSUT5 DD UNIT=SYSJA, SPAC E=(TRK, (25 ,3) ) , DSN=£SYSUT5 

XXSYSUT6 OD UN IT=SYSuA , SPA;E=( TRK, ( 25,3) ) ,DSN=£ SYSUT6 

XXSYSLIN DD OSNAME=£lOAuSET , OISP= ( MOD, PASS) ,UN IT=SYSDA , 

XX jPACE=(80,(500,lt>o)) 

//Ciib.SYSIN DD * 

IEF236I ALLOC. FOR TESTRUN COB 

IEF237I 5C0 ALLOCATED TO STEPLiB 

IEF23/I 5C0 ALLOCATED TO 

IEF237I 5C0 ALLOCATED TO 

IEF2371 jes Allocated to sysprint 

IEF237I JES ALLOCATED TO SYSUDJW 
IEF237I 272 ALLOCATED TO SYSUTx 

IEF237I 150 allocated to sysut^ 

IEF237I 272 ALLOCATED TO SYSUTj 

IEF237I 272 ALLOCATED TO SYSUTx 

IEF237I 272 ALLOCATED TO SYSUTx 

IEF237I 272 ALLOCATED TO SYSUTc 

IEF237I 272 ALLOCATED TO SYSLlN 

UEF237I jes allocated to sysin 



11MVS037 



00001000 
00002000 
00303000 
0000*000 
00005000 
00006000 
00007 000 
00008000 
00009000 
00010000 
00011000 
00012000 
00013000 
0001*000 
00015000 
03016000 
00017000 
03027000 
00028000 
00029000 
00030000 
00031000 

00032000 
00033000 
0003*000 
00035000 
00036000 
00037000 
00038000 
33039000 
00040000 
00041000 



Figure 87. Examples of Compiler Output (Part 1 of 4) 
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0CC01 
0C002 
C0C03 
JCCC4 
QCCC5 
CCCC6 



0UCE2 
0UC£3 

coc£4 

OGCE a 
JOGE6 



© 



lOtOlu IDENTIFICATION uIVlSION. 

10002o PROGRAM-ID. TcoTkUN. 

10003u AUTHOR. PROGRAMMtR NAME. 

10004u INSTALLATION. PALO ALTO DEVELOPMENT CENTER. 

10005J DATE WRITTEN. AJGUST C, 1976. 

lOGOfru DATE-COMPILED. «UG 24,1976 



10G74u STEP-7. IF NO-Or- JtPENDENTS IS EQUAL TO ' 

10075 j NO-0F-OEPE.NuE.MTS. EXHIBIT NAMED WORK- 

1007bu STEP-6. 

10077u STEP-6. CLOSE FiLE-2. 

lC078u STOP RUN. 



0" MOVE »Z" TO 
RECORD. GO TO 



© ® © 



INTRNL 

DNM=1- 

DN.M=1- 

DNM=1- 

DNM=1 

DNM=1 

DNM=1- 

DNM=i- 

DNH=1- 

DNM=1- 

DNM=1- 

DNM=1- 

DNM=1- 

DNM=i- 

DNM=1- 

0NM=1- 

DNM=1- 

DNM=1- 

DNM=1- 

DNM=1- 

DNM=1- 

DNM=2 

DNM=2 

DNM = 2 

DNM=2- 

0Nrt = 2 



NArtE 
a68 



j.a9 

i06 

47 
o7 
62 

y8 
-.12 
-30 
J48 
jc8 

64 
t08 
■*2B 
442 
•»61 
t7i> 
4*3 
vOO 
0^6 
j40 
joO 

71 



LVL 

FD 

01 

02 

FD 

01 

02 

77 

77 

01 

C2 

02 

02 

C2 

01 

02 

02 

02 

02 

02 

02 

02 

02 

01 

02 

02 



SOURCt M4ME 

FILE-i 

RECORu-i 

FIELU-A 

FILE-,; 

RECORu-2 

FIELD- A 

KOUNT 

NOMBtft 

FILLE* 

ALPHAoET 

ALPHA 

OEPENuENTS 

DEPENJ 

WORK-nECJkO 

NAMt-McLD 

FILLE* 

RECORu-Nu 

FILLfcK 

LOCATiOVi 

FILLER 

NO-OF-OEPENOENTS 

FILLtH 

RECORjA 

A 

3 



© © © 



© © 



© 



BASE 


DISPL 


INTRNL NAME 


DEFIMITIOM 


JSftGE 


R 3 3 M 


DCB=01 




DNM=1-148 






QSAM 




F 


BL = 1 


ooo 


ONM= 1-168 


OS 


o:l2o 


3 PGUP 






BL = 1 


003 


DNM=1-189 


DS 


2DC 


DISP 






DCB=02 




DNM=l-206 






QSAM 




F 


BL=2 


000 


DNM= 1-226 


OS 


0CL20 


GP3UP 






BL = 2 


000 


DNM=l-247 


DS 


23C 


DISP 






BL = 3 


000 


Df^H=l-267 


DS 


H 


COMP 






BL = 3 


002 


0NM=1-2B2 


DS 


IH 


C0MP 






BL = 3 


008 


DNM=l-298 


DS 


0CL52 


GROUP 






BL = 3 


008 


DNM= 1-312 


DS 


26C 


MSP 






BL = 3 


OOP 


DNM=l-330 


DS 


1C 


PISP 


» 




BL = 3 


022 


DN*1=l-348 


DS 


26: 


DISP 






BL=3 


022 


DNM=l-368 


DS 


1C 


DISP 


* 3 




BL=3 


040 


DNM=l-384 


DS 


0CL20 


GROUP 






BL = 3 


040 


DMH=l-408 


DS 


i: 


DISP 






BL=3 


041 


DNM=l-428 


DS 


1C 


DISP 






BL = 3 


042 


DNM= 1-442 


OS 


4: 


DISP-NM 






BL = 3 


046 


DNM= 1-461 


DS 


1C 


DISP 






BL = 3 


047 


0NM=l-475 


DS 


3C 


DISP 






BL = 3 


04A 


DNM= 1-493 


DS 


i: 


DISP 






BL = 3 


04B 


DNM=2-000 


DS 


2C 


DISP 






BL = 3 


04D 


0NM=2-026 


DS 


7C 


DISP 






BL=3 


058 


0NM=2-040 


OS 


0CL4 


GROUP 






BL = 3 


05P 


DNM=2-060 


DS 


4C 


DISP-NM 






BL = 3 


058 


0NM=2-071 


DS 


4P 


C0MP-3 


R 





© 



© 



MEMORY MAP 



TGT 



SaVc AREA 

SWITCH 

TALLY 

SJRT SAVE 

ENTRY-SAVE 

SORT CORE SIZE 



00318 

00318 
00360 
00364 
00368 
0036C 
00370 



LITERAL PCOL (HEX) 



005UO (LIT+Oj 
CC5Ca (LIT+2*) 



000000G1 Ov/IAICIO 0000001C 00000008 00000000 48140000 
00044000 OoOOOOCO COOOOOOO 



DISPLAY LITERALS (BCD) 
CC504 (LTL+3o) "WORK-RECORD* 



© 



PGT 



DEBUG LINKAGE AkEA 
OVERFLOW CELLS 
VIRTUAL CELLS 
PROCEDURE NAME ^ELLS 
GENERATED NAME uELlS 
OCB ADDRESS CELlS 
VNI CELLS 
LITERALS 
DISPLAY LITERAL^ 
PROCEDURE BLOCK CELLS 



00560 

00560 
0056C 
00570 
0059C 
005 9C 
005A0 
005A8 
005B0 
00504 
005 EO 



(REGISTER ASSIGNMENT 



© 



REO 6 


dL 


= 3 


REG 7 


6L 


= 1 


REG 8 


BL 


= 2 



® 



WORKING-STORAGE STARTS AT LOCATION OOOAO FOR A LENGTH OF 00060. 



Figure 87. Examples of Compiler Output (Part 2 of 4) 
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© 

*BEGI* 


© 


© 


© 




© 


© 




61 


' 


s 






0005 E4 




PN=02 


EQU 


* 










0C05E4 




START 


EQU 


* 










0005E4 


5t5 BO C 080 




L 


11,080(0,12) 


PBL = 1 








0005 E8 


5a FO C 024 




L 


15,024(0,12) 


VULB0FLW1) 








0005 EC 


05 IF 




BALR 


1,15 










0005EE 


OOjO303D 




DC 


X'OOOOOOBD' 






64 


*STEP-1 


0005F2 




PN=03 


EOU 


* 










0005F2 


58 FO C 024 




L 


15,024(0,12) 


V(UBOFLWl) 








0005F6 


05 IF 




BALR 


1,15 










0005F8 


OOJ00040 




DC 


X' 00000040' 






64 


OPEN 


0005 FC 
000600 


58 FO C 028 
05 EF 




L 

BALR 


15,028(0,12) 
14,15 


VULBCU)eG4) 








000602 


58 10 C 040 




L 


1,040(0,12) 


0CB = 1 








0006 06 


58 40 1 024 




L 


4,024(3,1) 










00060A 


D«i 02 4 Oil C 02D 




MVC 


011(3,4) ,020(12) 




V( ILBOEXTO) 






000610 


5i> 13 D 234 




ST 


1,234(0,13) 


SA3 = 1 








0C06J.4 


92 OF 234 




MVI 


234(13), X'OF' 


SA3=1 





© 



♦STATISTICS* 



SOURCE RECORD;, 



86 



DATA DIVISION STATEMENTS = 



25 



PROCEDURE DIVISION STATEMENTS = 



21 



♦OPTIONS IN El-FECT* 
♦OPTIONS IN EFFECT* 

♦ OPTIONS IN Ej-FECT* 

♦ OPTIONS IN El-FECT* 
♦OPTIONS IN EFFECT* 
♦OPTIONS IN ErFECT* 

(♦OPTIONS IN EFFECT* 



SIZE = 1*1072 BUF = 12288 LINECNT = 57 SPACE1, FLAGW, SEQ, SOURCE 

DMAP, PMAP, NOCLIST, NOSUPMAP, NOXREF, SXREF, LOAD, NODECK, QUOTE, >(DTPJN:, FLOW= 

NOTEKH, NONJM, NOBATCH, NONAME, C0MPILE=01, NOSTATE, N3RESIDENT, NODYNAM, NOLIB, NPSYNTAX 
OPTIMISE, SYHDMP, NOTEST, VERB, ZWB, SYST, NOENOJOB, N3LVL 

NOLST , \UFDECK,NOCDECK, LC0L2, L120, DUMP , NOADV , NOPRINT, 

NOCOUNJ, NOVBSUM, NOVBREF, LANGLVLI2) 

DEBUG t-ILt SIZE = 2 BLOCKS, 1024 BYTES 



® 



CATA NAMES 



A 

ALPHA 

ALPHABET 

8 

DEPEND 

DEPENDENTS 

FIELO-A 

FIELD- A 

FILE-1 

FILE-2 

KOINT 

LOCATION 

NAME-FIELD 

NO-GF-DEPENOlNTS 

NCM8ER 

RECORD-NO 

RECOKD-l 

RECCRD-2 

SECOKDA 

WCRK-RECORD 



PROCEDURE NArtfcS 



BEGIN 

STEP-1 

STEP-2 

STEP-3 

STEP-4 

STEP-5 

STEP-6 

STEP-7 

STEP-8 



OEFN 



0000 5 8 
000044 
wi00043 
J00059 
000047 
000045 
300029 
J00037 
000017 
300C18 
000040 
000053 
300049 
000055 
000041 
000051 
000028 
000036 
000057 
O00048 



000061 
000064 
00006 8 
000072 
000074 
000077 
000080 
u 00082 
000085 



CROSS-REFERENCE DICTIONARY 
REFERENCE 

000068 

000081 
000070 



000064 000072 000077 
000077 000080 000085 
000064 000068 000070 000074 

000068 

000070 000082 

000064 000068 000071 

000071 

000072 

000080 

000072 000080 000083 



REFERENCE 



000074 
000074 



000083 
000080 



Figure 87. Examples of Compiler Output (Part 3 of <l) 
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[CARD ERROR MESSAGE 



5 
5d 



IKF10o7I-W 
IKF21s»0I-W 



' DATE ■ SHOULD NOT BEGIN A-MARGIN. 

PICTURE CLAUSE IS SIGNED, VALJE CLAUSE UNSIGNED. ASSUMED POSITIVE. 



® 



COND CODE 0004 

KEPT 



KEPT 



(IEF142I TESTRJN COB - STEP WAS EXECUTED 

IEF235I CBLuJMPL 

IEF28M VOL SER NOS= CBLDEV. 

IEF285I CbLCOMPL 

IEF28:>I VOL iER NOS= CBLDEV. 

IEF285I CBLoPM 

IEF285I VOL SER NOS= CBLDEV. 

IEF28M JES<:.JOB00059.S00103 

IEF28M JES<_. JOB00059. S00104 

IEF28SI SYS7623 7.T091O56.RA0u0.TESTRUN.SYSUTl 

IEF285I VOL SER NOS= 222222. 

IEF285I SYS/o237. T091056. RAOoO. TESTRUN. SYSUT2 

IEF285I VOL SER NOS= OOOOOO. 

IEF2 6JI SYS7t>237.T091056.RA0u0.TESTRUN.SYSUT3 

IEF285I VOL SER NOS= 222222. 

IEF285I SYS76237.T09105o.RA0u0.TESTRUN.SYSUT4 

IEF285I VOL SER NOS= ZlZliZ. 

IEF28SI SYS 76237. T09 1056. RAOuO.TESTR UN. SYSUT5 

IEF285I VOL SER NOS= 222222. 

IEF28M SYS76237.T091056.RAOUO.TESTRUN. SYSUT6 

IEF285I VOL SER NOS= 222222. 

IEF28M SYS7623 7.T091056.RAi>c0.TESTRUN. LOADS ET 

IEF285I VOL SER NOS= 222222. 

IEF285I JfcSt.JOB00059.SI0101 
IEF37JI STEP /COB / START 762^7.0910 

IEF374I STEP /COB / STOP 76237.0911 CPU OMIN 04.48SEC VIRT 



KEPT 

SYSOUT 
SYSOUT 
DELETED 

DELETED 

DELETED 

DELETED 

PASSED 

DELETED 

PASSED 

SYSIN 



136K. SYS 212K 



Figure 87. Examples of Compiler output (Part 4 of ft) 



Listing of -job control sta tements 
associated with this job step . These 
statements are listed because 
MSGLE?EL=<1,1) is specified in the JOB 
statement. JCL statements with XX 
instead of // represent statements in 
a cataloged procedure. 



Allocation messages from the job 
scheduler . These messages provide 
information about the device 
allocation for the data sets in the 
job step. They appear after the job 
control statements in the compile, 
linkage edit, and execution job steps. 
For example: 

IEF237I 235 ALLOCATED TO SYSUT1 

indicates that the data set for SYS0T1 
has been assigned to the device 235. 

Source module listing . The statements 
in the source module are listed 
exactly as submitted except that a 
compiler-generated card number is 
listed in the first column of each 
line. This number is referred to in 
diagnostic messages, on the XREF or 
SX8EF listing, and in the object code 
listing. If NOM is specified, the 
programmer-encoded source numbers in 
columns 1 through 6 are used in each 
of these cases. (See the description 
of the NUM option under "Options for 
the Compiler.") The source module is 
not listed when the NOSO0RCE option is 
specified. 



The following notations may appear on 
the listing: 

C Denotes that the statement was 
inserted with a COPY statement. 
Statements copied will not be listed 
if SUPPRESS is indicated. 

** Denotes that the card is out of 
sequence. 

I Denotes that the card was inserted 
with an INSERT card. 

If DATE-COMPILED is specified in the 
Identification Division, any sentences in 
that paragraph are replaced in the listing 
by the date of compilation in the following 
format: 

DATE-COMPILED. month day, year 



*• glossary: The glossary is listed when 
the DMAP option is specified. The 
glossary contains information about 
names in the COBOL source program. 

A and F. The internal name generated 
by the compiler. This name is 
used in the compiler object code 
listing to represent the name used 
in the source program. It is 
repeated for readability. 

B. A normalized level number. This 
level number is determined by the 
compiler as follows: (1) the 
first level number of any 
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c. 



hierarchy is always 01 , and 
increments for other levels are 
always by one; (2) only level 
numbers 03 through 49 are affected 
— level numbers 66, 77, as well 
as 88 and FD, SD, RD, and CD 
indicators are not changed. 

The data name that is used in the 
source module. 



Note that the following Report writer 
internally generated data-names can 
appear under the SOURCE NAME column: 



Used to coordinate control 

break activities. 
Used by coding generated 

for GROUP INDICATE 

clause. 
Used by coding generated 

for TERMINATE statement. 
Used by coding generated 

for GENERATE statement. 
Generated report record 

associated with the file 

on which the report is to 

be printed. 
Build area for print record 
First or second position of 

RPT.RCD. Used for 

carriage control 

character. 
Beginning of actual 

information that will be 

displayed, second or 

third position of 

RPT.RCD. 
Used to hold code specified 

in CODE clause. 
Name generated from COLUMN 

clause in a level-02 

statement. 
Used for elementary level 

with SUM clause, but not 

with data-name. 
Used to save the total 

number of lines used by a 

report group when 

relative line numbering 

is specified. 



D and E. For data names, these 

columns contain information about 
the address in the form of a base 
and displacement. For file names, 
the column contains information 
about the associated DCB, DECB, 
and FIB, if any. 

G. This column defines storage for 

each data item. It is represented 
in assembler-like terminology. 
Figure 89 refers to information in 
this column. 

H. Usage of the data name. For FD 
entries, the file processing 



CTL. LVL 
GRP.IND 

TER, COD 
FRS.GEN 
-nnnn 



RPT.RCD 
CTL.CHR 



RPT.LIH 

CODE-CELL 
E. nnnn 

S.nnnn 

N.nnnn 



technique is identified (e.g. 
QSAM, BDAH, etc.) . For group 
items, GROUP is identified. For 
elementary items, the information 
in its USAGE clause is identified, 
or the USAGE that was specified on 
its group. 

I. A letter under column: 



S-Indicates 
redefines 

0~lndicates 
has been s 
data-name. 

Q-Indicates 
the object 
object of 
option of 

M-Indicates 
records of 



that the data-name 
another data-name, 
that an OCCURS clause 
pecified for that 

that the data-name is 

or contains the 
the DEPENDING ON 
the QCCUHS clause, 
that the format of the 

the file is: 



F = fixed 
? = variable 
U = undefined 
S = spanned 

I-Indicates an input CD in a 
teleprocessing application 

O-Indicates an output CD in a 
teleprocessing application 

5. Global Taples and Litera l Po ol: The 
global fable is listed when the PMAP, 
CLIST, or DMAP option is specified 
unless SDPMAP is also specified and an 
E-level diagnostic message is 
generated. A global table contains 
easily addressable information needed 
by the object program for execution. 
For example, in the Procedure Division 
source coding (3) , the address of the 
first instruction under STEP-1, 
namely: 

OPEN OUTPUT FILE-1. 

would be found in the PROCEDURE NAME 
CELLS entry of the Program Global 
Table (PGT) . 

A. Task Global Table (TGT) . This 
table consists of switches, 
addresses, and work areas whose 
information changes during 
execution of the program. 

B. Literal pool. The literal pool 
lists the collection of the 
literals in the program, with 
duplications eliminated. These 
literals include those specified 
by the programmer {e.g., MOVE 
"ABC" TO DATA-NAME) and those 
generated by the compiler (e.g., 
to align decimal points in 
arithmetic computation). The 
literals are divided into two 
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groups: those that are referred 
to by instructions (marked 
"LITERAL POOL") and those that are 
referred to by the calling 
sequences to object time 
subroutines (marked "DISPLAY 
LITERALS"). 



C. Program Global Table (PGT) - This 
table contains the remaining 
addresses and the literals used by 
the object program. 

For further discussion, see 
"Appendix J: Fields of the Global 
Table." 

Register Assi gn ment ; This contains 
the register assigned to each base 
locator (BL) in the object program. 



If OPT was specified, r 
through 9 (and register 
for the additional OVER 
the PGT) are perianentl 
the most f requently-use 
assignments are printed 
listing. Any additiona 
registers 14 and 15 ass 
as and when needed. Su 
assignments are not pri 
listing. 



egisters 6 

10 if not used 
FLOW cell of 
y assigned to 
d BLs. These 

in the 
1 BLs have 
igned to them 
ch temporary 
nted in the 



Working -storage: When PMAP, CLIST, or 
DMAP is specified, both the location 
and the length (in hexadecimal) of the 
Working-Storage section, if any, are 
provided. 

Object £ ode Listing: The object code 
listing is produced when the PMAP 
option is specified unless SOPMAP is 
also specified and an E-level error is 
encountered. The actual object code 
listing contains: 

A. The compiler-generated card number 
or source card number, if NOM is 
specified. The number refers to 
the COBOL statement in the source 
module that contains the verb 
listed under column B. 

B. The relative verb number for each 
card number. 

The statement within which the 
COBOL verb appears determines the 
information under columns C, D, F, 
and G. 

If VERB is specified in 
connection with PMAP or CLIST, 
procedure-names and verb-names are 
listed with the associated code. 
Names preceded by an * in column B 
are procedure-names. 



C. The relative location, in 
hexadecimal notation, of the 
object code instruction in the 
module. 

D. The actual object code instruction 
in hexadecimal notation. 

E. The procedure-name number. A 
number is assigned only to those 
procedure-names to which reference 
is made in other Procedure 
Division statements. This may be 
a PN (procedure-name) or GN 

(generated-name) number. 

F. The object code instruction in a 
form that closely resembles 
assembler language (with 
displacements in hexadecimal 
notation) . 

G. Compiler-generated information 
about the operands of the 
generated instruction. This 
includes names and relative 
locations of literals. Figures 89 
and 90 refer to information in 
this column. 

Note: The programmer can produce a 
condensed listing by specifying CLIST 
as an option in place of PMAP. The 
CLIST option produces only the source 
card number, the relative verb number, 
and the location of the first 
generated instruction, as follows: 



55 


VERB1 


0004AC 


58 


VERB1 


0004CO 


58 


VERB2 


0004F2 


62 


VERB1 


00050E 


62 


VERB 2 


00051A 


62 


VERB3 


000526 



9» Statistics: The compiler statistics 
list the options i n effect for this 
run and the number of Data Division 
and Procedure Division statements 
specified. Each level number is 
counted as one statement in the Data 
Division. Each verb is counted as one 
statement in the Procedure Division. 
COMPILE=nn indicates that this is the 
nth COBOL source program processed in 
this invocation of the compiler. If 
NOBATCH was in effect, this number 
will be 01. Note that COHPILE=nn is 
not an option that can be specified or 
controlled by the user, but is simply 
information produced by the compiler. 

Note: statistics are not printed if 
SYNTAX is in effect or if CSYNTAX is 
in effect and a D- or E-level error 
occurs. 

10. C ross- Ref e rence „ Dictionary : The XREF 
dictionary, produced when either the 
XREF or the SXSEF option is specified, 
consists of two parts: 



Output 237 



11. 



A. The XHEF dictionary for data-names 
followed by the generated number 
or source card number of the card 
on which the statement begins, if 
NUM is in effect. For condition 
names, the data -name of the 
conditional variable appears in 
the XSEF dictionary. 

B. The XREF dictionary for 
procedure-names followed by the 
generated number or source card 
number of the card on which the 
statement begins. 

For XREF, all the names begin in the 
order in which they are defined in the 
source program. For SXREF, the names 
appear sorted in alphanumeric order. 
The number of references appearing for 
a given name is based on the number of 
times the name is referred to in the 
compiler-generated code. {Some 
data- names in USE FOR DEBUGGING, 
STRING, UNSTRING, and SEARCH 
statements are not part of the 
compiler-generated code, and are 
therefore not listed in the cross 
reference output. 



D ia gn ostic messages : The diagnostic 
messages associated with the 
compilation are always listed. The 
format of the diagnostic message is: 

A. Compiler-generated line number or 
source card number. This is the 
number of a line in the source 
module related to the error. 

B. Message identification. The 
message identification for COBOL 
compiler diagnostic messages 
always begins with the symbols 
IKF. 

C. Severity level. There are four 
severity levels as follows: 

V Warning — This severity level 
indicates that an error was 
made in the source program. 
However- it *s not serious 
enough to hinder the execution 
of the program. These warning 
messages are listed only if 
FLAGW is specified. 



Conditional 
level indica 
was made but 
makes an ass 
some cases c 
The statemen 
error is ret 
can be attem 
debugging va 



— This severity 
tes that an error 
that the compiler 
umption, which in 
orrects the error, 
t containing the 
ained. Execution 
pted for its 
lae. 



E Error — This severity level 
indicates that a serious error 
has been detected. Usually the 
compiler makes no corrective 
assumption. The statement or 
operand containing the error is 
dropped. Execution of the 
program should not be 
attempted. 

D Disaster — This severity level 
indicates that a serious error 
was made. Compilation is not 
completed. Results are 
unpredictable. 

There is a correlation between 
severity level and the return 
codes referred to by the COND 
parameter. For example, a 
compilation in which a W- level 
error is detected generates a 
return code of 4; a C-level error, 
a code of 8; an E- level error, of 
12; and a D-level error, of 16. 

Message text. The text identifies 
the condition that caused the 
error and indicates the action 
taken by the compiler. 

Since Report Writer and 
SORT/MERGE generate a number of 
internal data items and procedural 
statements, some error messages 
may reflect internal names. In 
cases where the error manifests 
itself mainly in these generated 
routines, the error messages may 
indicate the card number of the RD 
entry for the report under 
consideration. In addition, there 
are errors that may indicate the 
card number of the card upon which 
the statement containing the error 
ends rather than the card upon 
which the error occurred. 
Messages for errors in the files 
refer to the card number of the 
associated SELECT clause. 
Internal name formats for Report 
Writer are discussed in the 
" Glossary. M 

When a programmer codes a verb, 
such as SEARCH, where the 
statement may span several lines 
and contain several verbs, such 
as G0 . T0 i M°VE' DISPLAY, etc., 
the diagnostic will reference 
the card number containing the 
most recently encountered verb, 
when that verb starts a new 
line. 
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12. Disposition messages,., from the job DjSPLA YIHG A LIST OF DIAGNOSTIC MESSAGES 
scheduler ; These messages contain 
information about the disposition of 

the data sets, including volume serial The user can generate a complete listing of 
numbers of volumes in which the data compiler diagnostic messages along with 
sets reside. 
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//ERRMSG JOB 

// EX EG 

//COB. SYS IN DD 

ID DIVISION. 

PROGRAM-ID. 

REMARKS. 



Oser Information 
COBUC 

* 



ERRMSG. 
THIS PROGRAM SILL RESULT IN A LISTING OF ALL 
COMPILER DIAGNOSTICS AND THEIR EXPLANATIONS. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

PROCEDURE DIVISION. 

* THE SAME RESULTS CAN BE ACHIEVED BY CHANGING 

* THE PROGRAM-NAME OF ANY PROGRAM TO » ERRMSG. • 
STOP RUN. 



/* 



Figure 88. A Program that Produces Compiler Diagnostics and Explanations 



Type 



Definition 1 



Usage 



1 

t Group Fixed Length 




1 DS 


OCLN 








1 


GROUP 


| Alphabetic 




J DS 


NC 








\ 


DISP 


] Alphanumeric 




J DS 


NC 








1 


DISP 


J Alphanumeric Edited 




| DS 


NC 








1 


AN-EDIT 


J Group Variable Length 




| DS 


VLI=N 








1 


GROUP 


) Numeric edited 




\ DS 


NC 








J 


NM-EDIT 


\ Sterling Report 




1 DS 


NC 








\ 


RPT-ST 


) External Decimal 




1 DS 


NC 








i 


DISP-NM 


1 External Floating Point 




J DS 


NC 








\ 


DISP-FP 


\ Internal Floating Point 




| DS 


1F2 or 


4C 






! 


COMP-1 






| DS 


1D* or 


8C 






1 


CO MP- 2 


I Binary 




1 DS 


1H2,1F* 


,2J 


2 ,2C, 


4C, 


8C| 


COMP 


| Internal Decimal 




1 DS 


NP 








1 


COMP-3 


\ Sterling Non-Report 




\ DS 


NC 








J 


DISP-ST 


j Index-Name 




| BLANK 








i 


INDEX-NAME 


I File <FD) 




] BLANK 








\ 


FILE PROCESSING TECHNIQUE 


1 Condition {88) 




| BLANK 








l 


BLANK 


] Report Definition (RD) 




i BLANK 








t 


BLANK 


| Sort Definition (SD) 
i 




| BLANK 
t 








I 


BLANK 


t 

l*In this column, N = size 


in 


bytes. 


except 


in 


group 


varia 


ble length where it is a 


| variable-length cell num 


ber. 
















|*If the SYNCHRONIZED clause appears, 


r these 


fields are 


used. 



-* 



Figure 89. Glossary Definition and Usage 



their explanations by attempting to compile 
a program with a program-name of ERRMSG 
specified in the PROGRAM-ID paragraph. An 
example of how to generate this listing is 
shown in Figure 88. 



I2i®5 Although the user can change the 
program-name of any source program to 
ERRMSG, the following compiler options must 
be in effect: NOCSYNTAX, NO DECK, NODMAP, 
NOFLOW, NO LOAD, NOOPTIMIZE, NOPMAP, 
NOSTATE, NOSYNTAX, NOSXREF, NOTERM, NOTEST, 
NOXREF; NOTERM prevents a display of the 
messages at the terminal. 



For a list of object- time messages, see 
"Appendix K: Diagnostic Messages." 



OBJECT MODULE 



The object module contains the external 
symbol dictionary, the text of the program, 
and the relocation dictionary. It is 
followed by an END statement that marks the 
end of the module. For more detailed 
information about the external symbol 
dictionary, text, and relocation 
dictionary, see the publication OS/VS 
Linkage Editor and Loader . 

An object module deck is punched if the 
DECK option is specified unless SUPMAP is 
specified and an E-level diagnostic message 
is generated, and if a SYSPUNCH DD 
statement is included. An object module /is 
written in an output volume if the LOAD 



Output 239 



option is specified unless SUPMAP is 
specified and an E-level diagnostic message 
is generated and if a SYS LIN DD statement 
is included. 



I Symbol 



J Definition 



BL JBase Locator 

BLL JBase locator for linkage 

| section 

CKP (Checkpoint counter 

DBGC J Debug card number 

DBGI J Debug information pointer 

DBGT } Debug transfer 

DCB JDCB address 

DEC JDECB address 

DNH J Source data name 

FIB J FIB address 

GN J Generated procedure name 

I NX 1 Index cell 

LIT JLiteral 

ON J On counter 

OVF | Overflow cell 

PBL J Procedure block (Optimizer) 

PFH J Perform counter 

PN f Source procedure name 

POV JPGT overflow 

PRH |Parameter 

PSV | Perform save area 

RSV J Report save area 

SAV jsave area cell 

SA2 J Input/Output error save cell 

SA3 JOPEN parameter 

SBL J Secondary base locator 

SBS jsubscript address 

SSVE JSort save area 

SHT | Switch cell 

TLY JTally cell 

TOV |TGT overflow 

TS jTemporary storage cell 

TS2 JTemporary storage 

1 (non-arithmetic) 

TS3 JTemporary storage 

J (synchronization) 

TS4 JTemporary storage 

J (table handling) 

V(BCDNAflE) J Virtual name 

VIR jvirtual cell 

VLC | Variable length cell 

VN | Variable procedure name 

VNI J Variable name initialization 

WC J Working cell 

XSA J Exhibit save area j 

XSH J Exhibit switch J 

i ; — i , __j 

Figure 90- Symbols Used in the Listing and 
Glossary to Define 
Compiler-Generated Information 



LINKAGE EDITOR OUTPUT 



The output of the linkage editor job 
step may include; 



• A printed listing of the job control 
statements 



• A map of the load module after it has 
been processed by the linkage editor 



» A cross-reference list 



• Informative messages 



• Diagnostic messages 



• Disposition messages 



* A listing of the linkage-editor control 
statements 



• A load module that must be assigned to 
a library 



Any diagnostic messages or informative 
messages associated with the linkage editor 
are automatically generated as output. The 
other forms of output may be reguested by 
the PARM parameter in the EXEC statement. 
All output to be listed is written in the 
data set specified by the SYSPRINT DD 
statement. 



Figure 91 is an example of linkage 
editor output listing. It shows the job 
control statements, informative messages, 
and module map. The different types of 
output are numbered and each type to be 
explained is lettered. The text following 
Figure 91 is an explanation of the 
illustration. 



2U0 



© 



© 



XXLAtO EXEC PGM-IEWL.PARM-'SPARMLKD'.REGION.tRGNLKED.^D.SCOilDKD 00042000 

XXSYSL1N DO OSNANE-t.LOADSET.DISP»(OLD.OELETEI 000*3000 

XX uO OONAME-SYSIN 000*4000 

XXSYSLMOO 00 0SNAM6»kGOSET(6GOI .DISP-I .PASS! .UNIT-SYSOA, 00045000 

XX >PACE-(TRK, (10,2,11) 00044000 

XXSVSLIB 00 DSN-&S*,»0L-SER-CV4,UNIT»£U4,DISP«SHR 00047000 

XX JO DSN»CS5.VOL-SEK»EV5,UNIT-eU5.0ISP«SHR 00048000 

XX liO 0SN-£S9,V0L-SV»,UNIT.tU9,0ISP-SHR 00049000 

XXSVSUT1 00 UNIT-(SYiDA,SEP»(SYSLIN,SYSLMOO)»,SPACE"(1024, (50,20)1 00050000 

//LitEO.SYSPRINT OD SYSOUT-S .,„,..„ 

Ix/SYSPRINT 00 SYSOUT-A 0U0510CC 
IEF237I 272 ALLOCATED TO SYSLln 
IEF237I OMY ALLOCATED TO 
IEF237I 150 ALLOCATED TO SYSLMuO 

UF2J7I sco allocated to syslid 

IEF237I 5C0 ALLOCATED TO 

IEF237I 5C0 ALLOCATED TO 

IEF237I 272 ALLOCATED TO SYSUT* 

IEF237I JES ALLOCATED TO SYSPR1NT 



(7)Ft4-LEVEL LINKAGE EOITOR OPTIuNS SPECIFIED LIST, LET, XREF 
^-^ DEFAULT OPTIONIS) UScD - S IZE«( 196608, 65536) 



CROSS REFERENCE TABLE 



O 
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W 
















CCNTROL SECTION 




ENTRY 
















NAME OkIGIN 


LENGTH 


NAME LOCATION 


NAME LOCATION 


NAME L3CATIDN NAME L 


CATI3 




TESTRUN 


00 


A76 


















ILBOOBG * 


A78 


E36 
























ILBOOBGO 


AAA 


ILB00BG1 


AAE 


ILB00BG2 


AB2 ILBPDBG3 


«*6 










ILB0DBG4 


ABA 


ILB00BG5 


ABE 


ILB3DBG6 


AC? ILB00BG7 


ACS 




ILBUOSP • 


18B0 


9F0 


ILBOOSPO 


18B2 


ILBODSSO 


1862 










ILBOEXT • 


<:2A0 


50 


ILBOEXTO 


22A2 


ILB0EXT1 


22A6 










ILBOFLH • 


22F0 


536 
























ILBOFLHO 


22F2 


1LBC1FLW1 


22F6 


1LB0FLW2 


22FA 




) 


ILBOQIO • 


*826 


56E 


ILBOOIOO 


282A 














1L8USRV * 


<i098 


48E 
























ILBOSKVO 


20A2 


ILB0SR5 


20A2 


ILB0SR3 


20A2 IIBOSP 


20A2 










ILB0SRV1 


2DA6 


ILB0STP1 


2DA6 


ILBOST 


20AA ILBOSTPO 


?DAA 




ILBOBEG » 


3228 


128 


ILBUBEGO 


3224 














ILBOCMM • 


3350 


38B 


IL60CNM0 


3352 


ILB0CMM1 


3356 










UBOCOMO» 


36E0 


169 


I LBOCOM 


36E0 














ILBOHSG > 


3850 


F2 






















ILBOHSGO 


3852 












© 




© 


© 
















LCCATICN r 


cFERS 


TO SYMBOL IN 


CONTROL SECTION 




L(i:»nm 


REFERS 


TO SYM30L I 


CONTROL SECTIPI" 






570 




ILBOSRVO 


ILBOSRV 




574 




ILBODSC-O 


IL3O0B3 






578 




IL8OFLM0 


ILBOFLH 




57C 




ILB0DB05 


HPPPPr. 






580 




ILB0SR5 


ILFOSRV 




584 




ILP0FLW1 


ILPPFLW 






588 




IL60J3G4 


ILBiTOBG 




56C 




U33EKT0 


IL30E/T 






590 




ILBUQIOO 


ILBOJIC/ 




594 




ILKODSPO 


u?rpsp 




) 


598 




ILB0SRV1 


ILPOSPV 




4H0 




1LB0COM0 


ILtOCOMO 






1774 




IL3OFLW0 


ILPOFLW 




I77f. 




1L80FLW2 


HPPFLrt 






177C 




ILB0TEF3 


tUNRCSOLVEDUl 




1780 




ILBOSTNO 


(UMPESOLVEPIHI 






1788 




ILBOTCOO 


HJNkESOLVEDUl 




30t£, 




ILBOCOH 


ueoco«o 






30EC 




[LBGCMMO 


ILBOCMM 




30F0 




IL BOB ECO 


1LP0PEG 






30F4 




ILBCHSGO 

oo© 

3948® 


ILBOMSG 




30FP 




[LB0SNC2 


JUNPESOLVED(W) 




| ENTRY ADGRtS 


o 
















(total LEN»TH 


















«*»»0j 


uJES 


NUT EXIST ouT 


HAS BEEN ADDED TO 


fiATA SET 












A 


UTriCklZATIoN 


CODE 


IS 
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1EF142I 


TESTRJN LKci) - STEP MA„ c 


XcCUTEO 


- CONO CODE 


0000 


[EF2851 


SYSfo237.T0<'1056.PAu„0 


I ESTKUN 


LOAJSET 




OELbTCD 


IEF285I 


VOL Sck NuS* 222222. 










IcF28:>l 


SYS7o237.TU91056.RA0.i0 


TtSTRUN 


GOSET 




PASSED 


lEF2d>I 


VUL SEK hOS« 000000. 










Icf2a51 


CVS-ULIB 








KEPT 


IEF283I 


VLL SEK NUS= CBIDEV. 










IEF28SI 


CVS^UllB 








KEPT 


I£f28:>l 


VOL SER *uS= CbLDfcV. 










IEF2S51 


CVS.-l.Lle 








KEPT 


IcF26jI 


VOL StK Nl'S= CoLJiV. 










Ifcf2d=I 


SYS/o2_>7.T09105t>.KAOuO 


TtSThOf' 


ROcOOOJl 




OFLETtD 


ltF^i■Jl 


VOl It.K NLi5= 222222. 










[EFidjl 


Jt?^.Jlli)0Ci.5'.-..SjJl03 








SYSOJT 


IcF37jI 


aTtP /LKEj / START It, 


j7.0-»ll 








ICF37-.I 


STLP /LKED / STOP It 


;>7.imi 


CPU OHIN 


01 


.50SFr V 



Figure 91- Linkage Editor Output showing Sodule Sap and Cross-Reference List 



!• fhe job contr ol sta teme nts- These 
statements are listed because 
HSGLEVEL= (1,1) is specified on the JOB 
statement for this job, shown in 
Figure 87. 



2 . Allocation messages from the jo b 
scheduler . These messages provide 
information about the device 
allocation for the data sets in the 
job step- For example, the message 

IEF2371 230 ALLOCATED TO SYSUT1 



Linkage editor inform ative me ssage. 
This message lists the PARM options 
that were specified. 



4. Li nkage editor inform ative message. 
This is a disposition message 
describing the disposition of the load 
module. 



A- Name of the load module specified 
in the DSNAME parameter of the 
SYSLMOD DD statement 



indicates that the data set for SYSUT1 
has been assigned to the device 230. 



B- Text of message 
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5- Module ma p. The module map is listed 
when either the XREF or the HAP option 
is specified in linkage editor 
processing. The module map shows all 
control sections in the output module 
and all entry names in each control 
section. The control sections are 
arranged in ascending order according 
to their assigned origins. All entry 
names are listed below the control 
section in which they are defined. 
Each COBOL program is a control 
section, and any COBOL library 
subroutine is a separate control 
section (except as noted under 
segmentation) . 



A. Control section. Under this 
heading the name, origin, and 
length of each control section is 
listed. 

Name. The name of the control 
section. This name is the 
PROGRAM-ID name in the main COBOL 
program or a called program. Each 
control section that is obtained 
from a library by an automatic 
library call is indicated by an 
asterisk. 

Or igin. The relative origin in 
hexadecimal notation. 
L engt h. The number of bytes in 
each control section in 
hexadecimal notation. 



B - Entry. The entry names within 
each control section and their 
relative location. A called 
program may have more than one 
entry point. For a called COBOL 
program, the entry points are the 
same as the names specified by the 
ENTRY statements in the source 
program. 

c - Entry add ress. The relative 
address of the instruction with 
which processing of the module 
begins. It will always be IHIT1 
if the COBOL program is the main 
program of the load module. 

D. Total length . The total number of 
bytes, in hexadecimal notation, of 
the load module. It is the sum of 
the lengths of all control 
sections. 



Cross reference _, jL |.s t. The cross 
reference list, as well as a module 
map, is listed if the XBEF option is 
specified. The HAP and XBEF options 
should not be specified together. The 
cross reference list provides the 
following information: 



A. L ocat ion. The relative location 
in the program where another 
program is called. 

B. Sy mbol referen ce. The name of the 
entry point of the called program. 

C. In control section. The control 
section that contains the entry 
point. 

For example, 410 is the location where 
a COBOL subroutine is called. 
ILBOSRV1 is the entry point of the 
called program. ILBOSRV0 is the 
control section that contains the 
entry point ILB0STP1. 

If XREF is specified, the cross 
reference list appears before the 
Entry Address. 



7 • Disppsition messages, from the job 

scheduler. These messages contain 
information about the disposition of 
the data sets. 



Comments on the Module flap a nd Cross 
Reference List 



The severity of linkage editor 
diagnostic messages may affect the 
production of the module map and the cross 
reference list. 

Since various processing options will 
affect the structure of the load module, 
the text of the module map and cross 
reference list will sometimes provide 
additional information. For example, the 
load module may have an overlay structure. 
In this case, a module map will be listed 
for each segment in the overlay structure. 
The cross reference list is the same as 
that previously discussed, except that 
segment numbers also are listed to indicate 
the segment in which each symbol appears. 

Listi ng the Li nkage E ditor Contr ol 
St atem ents: if the LIST option is 
specified, linkage editor control 
statements, such as OVERLAY and LIBRARY, 
are listed. 



Linkage Editor Message s 



The linkage editor generates two types 
of messages: module disposition messages 
and error/warning messages. A description 
of the messages can be found in the 
publication OS/YS Linkage Editor and 
Loa der. A complete list of the 
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error/warning aessages is included in the 
publication OS/YS Mes sage Li brary; linkag e 
Editor and Loader Messages „ 



LOADER OPTPUT 



Loader output consists of a collection 
of diagnostic and error messages, and, if 
MAP is specified, a storage nap of the 
loaded program. The output data set, 
SYSLOUT is sequential and blocked as 
specified by the user in the DCB. For 
better performance, the user can also 
specify the number of buffers to be 
allocated. 

Diagnostic messages include a loader 
heading and a list of options requested by 
the user. The error messages, identifying 
the source of error. Hill be written when 
the error is detected. After processing is 
complete, an explanation of the error will 
be written. A complete list of loader 
error messages is found in the publication 

OS/IS, Message .LjpraxXi Lia£ag;e_Editor a&d 

Lo ad er Messages. 

The map includes the name and absolute 
address for each control section and entry 
point defined in the program. It is 
written on SYSLOUT concurrently with input 
processing so it appears in order of input 
ESD items. The total size and storage 
extent also are included. Figure 92 is an 
example of a module map. 



COBOL LOAD MODULE EXECUTION , 00 TPOT 

The output generated by program 
execution (in addition to data written in 
program output files) can include: 

• Data displayed on the console, or on 
the printer 

• Cards 

» Messages to the operator 

• System informative messages 

• System diagnostic message 



• A system dump 



• Debugging information 

Note : If a program ends abnormally and 
one of the options FLOW, STATE, or SYMDMP 
is in effect and the SYSDBOUT DD card has 
been included, debugging information 
appears in the program listing (see the 
chapter entitled "Symbolic Debugging 
Features") . 

A dump as well as system diagnostic 
messages are generated automatically if a 
program contains errors that cause abnormal 
termination. 



Jgote: If a COBOL progr 
terminates, then a form 
provided for all COBOL 
with the SYMDMP option 
the abnormally terminat 
callers, up to and incl 
program. For a discuss 
option as well as of ot 
debugging options, see 
"Symbolic Debugging Fea 



am abnormally 
atted dump is 
programs compiled 
which could include 
ing program and its 
uding the main 
ion of the SYMDMP 
her COBOL symbolic 
the chapter entitled 
tures. " 



Figure 93 shows an example of output 
from the execution job step. The following 
text is an explanation of the illustration. 

1- 2,he„,job„,control .statements. These 
statements are listed because 
MSGLEVEL=(1, 1) is specified in the JOB 
statement for this job. 

2 . The j ob a llocation messages from the 
job scheduler. These messages indi- 
cate the device that is allocated for 
each data set defined for the job 
step. 

3- disposition messages from the job 
scheduler. These messages are 
contained in the OS/VS message 
library. 

***. Program output_on printer. The 

results of execution of the TRACE and 
EXHIBIT NAMED statements appear on 
program listing. 

5. C onsole outpu t. Data is printed on 
console as a result of execution of 
DISPLAY UPON CONSOLE. 
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VS LOADER 
OPTIONS USED - PRINT,MAP,LET,CALL,RES f NOTERM,SIZE=98304,NAME=**GO 



NAME TYPE 


ADDR 


NAME TYPE 


ADDR 


NAME TYPE 


ADDR 


NAME TYPE 


ADDR 


NAME T 


YPE 


ADDR 


TESTRUN 


SD 


60010 


























IEW1141 INCLUDE SYSLIB(ILBODSP) 
























ILBOCOMO* 


SD 


60940 


ILBOCOM * 


LR 


60940 


ILBOSRV * 


SD 


60A00 


ILBOSRV0* 


LR 


60A3A 


ILBOSR3 * 


LR 


60A3A 


ILBOSR5 * 


LR 


60A3A 


ILBOSR * 


LR 


60A3A 


ILBOSRV1* 


LR 


60A3E 


ILBOSTP1* 


LR 


60A3E 


ILBOST * 


LR 


60A42 


ILBOSTPO* 


LR 


60A42 


ILBODSP * 


SD 


60DC0 


ILBODSP0* 


LR 


60DC2 


ILBODSS0* 


LR 


60DC2 


ILBOEXT * 


SD 


615A0 


ILBOEXTO* 


LR 


615A2 


ILBODBG * 


SD 


615C0 


ILBODBG 0* 


LR 


615C2 


ILBODBG1* 


LR 


615C6 


ILBODBG2* 


LR 


615CA 


ILBODBG 3* 


LR 


615CE 


ILBODBG4* 


LR 


615D2 


ILBODBG5* 


LR 


615D6 


ILBOFLW * 


SD 


621F8 


ILBOFLW0* 


LR 


621FA 


ILBOFLW1* 


LR 


621FE 


ILBOFLW2* 


LR 


62202 


ILBOMSG * 


SD 


62678 


ILBOMSG0* 


LR 


6267A 


ILBOBEG * 


SD 


62778 


ILBOBEGO* 


LR 


6277A 


ILBOCMM * 


SD 


627E8 


ILBOCMM0* 


LR 


627EA 


ILBOCMM1* 


LR 


627EE 








TOTAL LENGTH 


2B68 


























ENTRY ADDRESS 


60010 
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WARNING - CARD RECEIVED NOT AN OBJECT RECORD 



Figure 92. Module Map Format Example 
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IEF236I ALLOC. FOR TESTRUN GO 

IEF237I 232 ALLOCATED TO PGM=*.DD 

IEF237I 235 ALLOCATED TO STEPLIB 

IEF237I 250 ALLOCATED TO DD1 

IEE237I 250 ALLOCATED TO SYSDBOUT 

IEF237I 250 ALLOCATED TO SYSUDUMP 

IEF237I 250 ALLOCATED TO SYSOUT 

IEF237I 250 ALLOCATED TO SYSPUNCH 
»W« 2371 582 ALLOCATED TO SAMPLE 

XXGO EXEC PGM=*.LKED.SYSLMOD,COHD=((5,LT,COE),(5,LT LKED) ) 
XXSTEPLIB DD DSN=VSCBL1.LIB,DISP=SHR,UNIT=2314.V0L=SER=DB143 
XXDD1 DD DSN=»SYMDBG,DISP=(OLD, DELETE) 
//GO. SYSDBOUT DD SYSOUT=G 
X/SYSDBOUT DD SYSOUT=A 
//GO. SYSUDUMP DD SYSOUT=G 
X/SYSUDUMP DD SYSOUT=A 
//GO. SYSOUT DD SYSOUT=G 
X/SYSCUT DD SYSOUT=A 
XXSYSPUNCH DD SYSOUT=E 
//GO.SAMPLE DD UNIT=240O ,.LABEL={,NL). DISP=(NEW, DELETE) 



00800270 
00800280 
00800290 



00800320 
00800330 



© 



© 



© 



0004 NYC 

0005 NYC 

0006 NYC 

0007 NYC 



0015 NYC 

0016 NYC 

0017 NYC 

0018 NYC 

0019 NYC 

0020 NYC 



WORK-RECORD = A 0001 NYC Z 
WCRK-FECORD = B 0002 NYC 1 
WORK-RECORD = C 0003 NYC 2 
WORK-RECORD = D 
WORK-RECORD = E 
WCRK-RECORt = F 
WORK-RECORD = G 
WORK-RECORD = H 0008 NYC 
WORK-RECORD = I 0009 NYC 
WCRK-RECORD = J 0010 NYC 
WORK-RECORD = K 0011 NYC 
WCRK-RECORD = L 0012 NYC 
WORK-RECORD = M 0013 NYC 
WORK-RECORD = N 0011 NYC 
WORK-RECORD = 
WORK-RECORD = 
WORK-RECORD = 
WORK-RECORD = 
WORK- RECORD = 
WCRK-RECORD = 
WORK-RECORD = U 0021 NYC Z 
WORK-RECORD = V 0022 NYC 1 
WORK-RECORD = W 0023 NYC 2 
WORK-RECORD = X 002H NYC 3 
WORK-RECORD = Y 0025 NYC 4 
WORK-RECORD = Z 0026 NYC Z 
A 0001 NYC 
B 0002 NYC 1 
C 0003 NYC 2 
D 0001 NYC 3 
E 0005 NYC 4 
F 0006 NYC 
G 0007 NYC 1 
H 0008 NYC 2 
I 0009 NYC 3 
J 0010 NYC 4 
K 0011 NYC 
L 0012 NYC 1 
M 0013 NYC 2 
N 0014 NYC 3 
O 0015 NYC 4 
P 0016 NYC 
Q 0017 NYC 1 
R 0018 NYC 2 
S 0019 NYC 3 
T 0020 NYC 4 
U 0021 NYC 

V 0022 NYC 1 
W 0023 NYC 2 
X 0024 NYC 3 

Y 0025 NYC 4 
Z 0026 NYC 

IEF142I - STEP WAS EXECUTED - COND CODE 0000 

IEF285I SYS74163.T204211.RV0OO. TESTRUN. LMODLIB PASSED 

IEF285I VOL SER NOS= 231402. 

IEF285I VSCBL1.LIB KEPT 

IEF285I VOL SER NOS= DB143 . 

IEF285I SYS74163.T2O4211.RV000. TESTRUN. SYMDBG DELETED 

IEF285I VOL SER NOS= 333001. 

IEF285I SYS74163.T204211.SV000. TESTRUN. R0000011 SYSOUT 

IEF285I VOL SER NOS= 333001. 

IEF285I SYS74163.T2O4211.SV000. TESTRUN. R0000012 DELETED 

IEF285I VOL SER NOS= 333001. 

IEF285I SYS74163.T204211.SV000. TESTRUN. R0000013 SYSOUT 

IEF285I VOL SER NOS= 333001. 

IEF285I SYS74163.T204211.SV000. TESTRUN. R0000014 DELETED 

IEF285I VOL SER NOS= 333001. 

IEE285I SYS74163. T204211.RV000. TESTRUN. R0000015 DELETED 

IEF285I VOL SER NOS= L00001. 

IEF285I SYS74163.T204211.RV000. TESTRUN. S0000016 SYSIN 

IEF285I VOL SER NOS= 333001. 

IEF285I SYS74163.T204211.RV000. TESTRUN. S0000016 DELETED 

IEF285I VOL SER NOS= 333001. 

IEF373I STEP /GO / START 74163.2056 

IEF374I STEP /GO / STOP 74163.2109 CPU 0MIN 09.47SEC STOR VIRT 

IEE2851 SYS74163.T204211.RV000.TESTRUN.LMODLIB DELETED 

IEF285I VOL SER NOS= 231402. 

IEF375I JOB /TESTRUN / START 74163.2046 

IEF376I JOB /TESTRUN / STOP 74163.2109 CPU 0MIN 24. 47SEC 



Figure 93. Execution Job Step Output 
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REQUESTS FOR OUTPUT 



1. 



3. 



The programmer caa request data to be 
displayed by using the DISPLAY 
statement and including the following 
in the job control procedure: 



//SYSOUT 



DD SYSOUT=A 



Message to the operator can also be 
displayed on the console when 
requested in the source program 
(DISPLAY UPON CONSOLE) . 

The programmer can request debugging 
information in case of an abnormal 
termination by specifying FLOW, STATE, 
or SYMDMP and including the following 
in the job control procedure: 

//SYSDBOUT DD SYSOUT=A 

In addition, the SYSUT5 DD statement 
is required for compilation and the 
SYSDBG DD statement is required at 
execution time. 



Both SYSUDUMP 
usually produ 
abnormal term 
system contro 
addition to u 
modules, and- 
records if th 
running. SYS 
produces the 



and SYSABEND will 
ce the following when an 
ination occurs: some 
1 blocks, work areas (in 
ser modules) , and system 
-under VS2 — GTF trace 
at system service is 
ABEND normally also 
system nucleus. 



Dumps and debugging facilities are further 
explained in "Program Checkout." 



OPERATOR MESSAGES 



The COBOL load module may issue operator 
messages. A complete list of these 
messages and required operator responses 
can be found in "Appendix K: Diagnostic 
Messages." MCS considerations are 
discussed there also. 



The following DD statement must be 
used to make the COBOL library module 
ILBOBEG available at execution time. 

//STEPLIB DD DSN=subr-libname,DISP=SHR 

If an error message is printed by the 
debugging modules, the COBOL library 
module ILBOBEG is loaded dynamically 
from the subroutine library. This 
module is not link edited into the 
COBOL object program. 

By specifying a //SYSDTERM DD card in 
addition to the //SYSDBOUT DD card, 
dynamic dump output will be written 
onto SYSDTERM while the abend dump 
output will go to SYSDBOUT. 



Note: The TSO programmer should assign 
SYSDTERM to the terminal since dynamic dump 
output is interruptable. SYSDBOUT should 
be assigned to a direct access data set 
which could be listed at the terminal after 
the ABEND is complete. 

*. The programmer can request a full 
dump, in case his program is 
terminated abnormally, by including 
one of the following in the job 
control procedure: 

either 

//SYSUDUMP DD SYSOUT=A 

or 

//SYSABEND DD SYSOUT=A 



SYSTEM OUTPUT 



Informative and diagnostic messages may 
appear in the listing during execution of 
any job step. Further information about 
system diagnostics is found in the 
appropriate OS/VS Message Library 
publication. COBOL messages and associated 
documentation for this compiler can be 
displayed by running the-ERRMSG program 
described earlier in "Output." 



Each of these messages contains an 
identification code in the first three 
columns of the message to indicate the 
portion of the operating system that 
generated the message. Figure 94 lists 
these codes, along with an identification 
of each. 



1 — 
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|Code 
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I 

J ICE 


1 

1 


A 


message 


from 


i 

the Sort program. | 


IIEA 


1 


A 


message 


from 


the supervisor. I 


JIEC 


1 


A 


message 


from 


data management. J 


|IEF 


i 


A 


message 


from 


the job scheduler. J 


JIKF 


! 


A 


message 


from 


the COBOL compiler.! 


JIER 


I 


A 


message 


from 


the Sort program. | 


JIEW 


I 


A 


message 


from 


the linkage editor. f 


JIGH 


I 


A 


message 


from 


the Sort program. | 


I , 


-JL. 








_ j 



Figure 94. 
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PBOGHAH CHECKOUT 



A programmer using the COBOL compiler 
under OS/VS has several methods available 
to him for testing and debugging his 
programs or revising them for increased 
efficiency of operation. 

The lister feature provides the COBOL 
programmer with reformatted source code 
that contains complete cross-reference 
information at the source level. 

The syntax-checking options can be 
specified to save programmer and machine 
time while checking the source statements 
for syntax errors. 

The COBOL debugging language can be used 
by itself or in conjunction with other 
COBOL statements. A dump can also be used 
for program checkout. For a discussion of 
the COBOL symbolic debugging options, see 
the chapter entitled "Symbolic Debugging 
Features." 

The execution frequency statistics 
option, COUNT, facilitates testing, 
debugging, and optimizing by causing verb 
execution counts to be generated at the end 
of the execution of a compiled program. 
The statistics provide the COBOL programmer 
with information that aids user program 
optimization by identifying heavily-used 
portions of the COBOL source program. They 
are also useful to the programmer in 
debugging by providing verification that 
all parts of a program have been executed. 

Note: The program product IBM OS COBOL 
Interactive Debug (Program Number 57 34-CB4) 
enables the user to debug his COBOL 
programs from a terminal under TSO, the 
Time Sharing Option of the operating 
System. With its own debugging command 
language. Interactive Debug gives the user 
several object- time debugging capabilities 
including: starting and stopping program 
execution at selected points, altering the 
logical flow of program execution, 
manipulating data, and displaying such 
things as selected source statements, file 
status and content, and various kinds of 
program execution traces. How to 
accomplish these operations is described 
fully in IBB OS COBOL Interactive Debug 
Termin al U s er's Guid e and Re ferenc e . 

Specifying the TEST compiler option allows 
a COBOL program to be debugged by the 
Interactive Debug user. A program that is 
compiled without the TEST option is 
unacceptable to the Interactive Debug 
command processor. 



TEST has the following effects on other 
compiler options: TEST overrides FLOW, 
STATE, SYHDHP and COUNT. However, BATCH 
overrides TEST. TEST is also overridden if 
the source program contains USE FOR 
DEBUGGING and WITH DEBUGGING MODE 
statements. 

TEST requires the debug file, SYSUT5. 



LI STE8 FEATUBE 



When the user requests the lister 
feature, each COBOL statement is begun on 
new line and is indented in such a vay as 
to make the logic of the program readily 
apparent by highlighting level numbers, 
nested IF statements, etc. For complete 
information, see the chapter "Lister 
Feature." 



SYNTAX-CHECKING ONLY COMPILATION 



The compiler checks the source text for 
syntax errors and then generates the 
appropriate error messages, but does not 
bother to produce object code. With the 
syntax-checking feature, the programmer can 
request a compilation either conditionally, 
with object code produced only if no 
messages or just W- or C-level messages are 
generated, or unconditionally, with no 
object code produced regardless of message 
level. 

For a discussion of the syntax-checking 
options, SYNTAX and CSYNTAX, see the 
section "Options for the Compiler" under 
"Job Control Procedures." 



DEBUGGIHG LANGUAGE 



The COBOL debugging language is designed 
to aid the COBOL programmer in producing an 
error- free program in the shortest possible 
time. The sections that follow discuss the 
use of the various types of debugging 
language and other methods of program 
checkout. 
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DEBUGGING LINES 



The user can include debugging lines 
(any COBOL statement with a D in column 7) 
in his program to assist in locating logic 
errors. Through inclusion of the WITH 
DEBUGGING MODE source clause (essentially a 
compile- time switch) , the statements are 
made part of the object code and sill be 
executed in line with the rest of the 
program. Removal of the HITH DEBUGGING 
MODE clause causes debugging lines to be 
treated as comments only; they will not be 
executed. A program containing debugging 
lines must be syntactically correct in both 
these modes. (The execution-time option 
DEBUG/NODEBUG has no control over debugging 
lines; it only affects USE FOB DEBUGGING 
declaratives — as explained below.) 



DECLARATIVE PROCEDURES— USE FOR DEBUGGING 



The USE FOR DEBUGGING 
the user with the abilit 
procedures to examine th 
of his program during it 
USE FOR DEBUGGING statem 
which program elements i 
monitor. COBOL then giv 
procedure control when t 
referenced during execut 
also is given access to 
special register, which 
automatically filled wit 
current status informati 



feature provides 
y to create his own 
e internal status 
s execution. The 
ent identifies 
t wishes to 
es the associated 
hese elements are 
ion. The procedure 
the DEBUG-ITEM 
has been 
h the pertinent 
on. 



The USE FOR DEBUGGING procedures can be 
controlled by two switches: the HITH 
DEBUGGING MODE source clause for 
compile-time, and the DEBUG/NODEBUG option 
for execution-time. WITH DEBUGGING MODE 
indicates that the procedures are to be 
compiled as executable code; if WITH 
DEBUGGING MODE is omitted, the procedures 
are treated only as comments. 
Specification of the DEBUG option at 
execution time indicates that the 
procedures compiled into the code are in 
fact bo be executed; if NODEBUG is 
specified, the procedures are bypassed. 

The general rules for USE FOR DEBUGGING 
declarative procedures and the DEBUG-ITEM 
special register can be found in IBM_VS 
COBOL for QS/VS. The following 
considerations also apply: 

1. Including USE FOR DEBUGGING 

declarative procedures and a WITH 
DEBUGGING MODE clause precludes the 
use of the SYMDMP and TEST options. 
If SYMDMP and/or TEST are specified in 
such a case, they will be rejected. 



2. The DEBUG-ITEM special register is 
variable in length, and depends on the 
size of the character string it is to 
contain. This length cannot exceed 

3 2K. 

3. A SEARCH or SEARCH ALL statement that 
refers to identifier- 1 as the table to 
be searched will not result in an 
invocation of the USE FOS DEBUGGING 
declarative procedure. If 
identifier- 1 is referred to elsewhere 
in the statement (for example, as an 
operand of a WHEN condition) , the 
associated declarative will be 
invoked. 

4. When identifier- 1 is the object of an 
OCCURS DEPENDING ON clause, the 
contents of the DEBUG-CONTENTS 
subfield of DEBUG-ITEM will be 
unpredictable if all three of the 
following conditions are true: 

a) identifier-1 is changed in the same 
statement as the data item whose 
size and/or location is affected by 
that change, and 

b) the change occurs following the 
reference to the data item, and 

c) the data item is not subscripted 
and/or indexed. 

5. If identifier-1 appears in a MOVE 
statement and is subscripted or 
indexed, and if either of the 
following is also true: 

a) the subscript or index is changed in 
the MOVE prior to the reference to 
identifier- 1, or 

b) an OCCURS DEPENDING ON object that 
affects the size or address of 
identifier-1 is changed in the MOVE 
prior to the reference to 
identifier-1 , 

then the DEBUG-ITEM values will 
reflect identifier-1 ' s address and 
size just prior to execution of that 
MOVE. 

6. Procedures performed from a USE FOR 
DEBUGGING declarative will never cause 
invocation of another USE FOR 
DEBUGGING declarative. 

7. A USE FOR DEBUGGING filename can only 
be a VSAM or QSAM file. 

Figure 95 shows an elementary example of 
USE FOR DEBUGGING. The program is the same 
TESTRUN used several times elsewhere in 
this manual. Here it has been slightly 
modified through the addition of the 
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debugging phrase {encircled 1) and a simple 
declarative (encircled 2). In this 
example, the programmer wishes to 
temporarily trap certain input items (ALPHA 
D*s and M*s) and boost their index values 
by one so that they become E's and N's 
(encircled 3) . 

Notice that the DEBUG-CONTENTS special 
register allows the programmer to reference 
items without using subscripting. Notice 



also that the subscript value can be 
modified in the declarative section without 
affecting that value in the body of the 
program {i.e., DEBUG-SUB-1 is only a copy) . 
By removing the WITH DEBUGGING MODE clause 
from the CONFIGURATION SECTION and 
recompiling, the programmer can disable the 
debugging declarative — even though the 
declarative statements are left in the 
source program. 
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IDENTIFICATION Ul VISION. 
PROGRAM-ID. TEiTDBUG. 

AUTHOR. PROGRAMMER NAME. 

INSTALLATION. PALO ALTO DEVELOPMENT CENTER. 
DATE WRITTEN. AUGUST 8, 1976. 
DATE-COMPILED. SEP 10.1976. 

REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROSRAM FOR 
COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK AS 
INPUT. 

ENVIRONMENT DIVISION. 
CONFIGURATION StCTION. 

SOURCE-COMPUTcR. IBM-370 WITH DEBUGGING MODE. 
OBJECT-COMPUTtR. IBM-370-168. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-1 ASSIGN TO UT-2400-S-SAMPLE. 
SELECT FILE-2 ASSIGN TO UT-2400-S-SAMPLE. 

DATA DIVISION. 
FILE SECTION. 
FO FILE-1 

LABEL RECORDS ARE OMITTED 

BLOCK CONTAINS 100 CHARACTERS 

RECORD CONTAINS 20 CHARACTERS 

RECORDING MuOfc IS F 

DATA RECORD IS RECORD-1. 
01 RECORD-1. 

02 FIELD-A PICTURE IS X<20). 
FD FILE-2 

LABEL RECORDS ARE OMITTED 

BLOCK CONTAINS 5 RECORDS 

RECORD CONTAINS 20 CHARACTERS 

RECORDING MuDE IS F 

DATA RECORD IS RECORD-2. 
01 RECORD-2. 

02 FIELD-A PICTURE IS X120). 

WORKING-STORAGE SECTION. 

77 KOUNT PICTURE S99 COMP SYNC. 
77 NOMBER PICTURE S99 COMP SYNC. 
01 FILLER. 

02 ALPHABET PICTURE X<26) VALUE "ABCDEFGHIJKLMNOPQRST JVrfXYZ" . 

02 ALPHA REDEFINES ALPHABET PICTURE X OCCURS 26 TIMES. 

02 DEPENDENTS PICTURE X(26) VALUE "0123*0123*012340123401234 

"0". 

02 depend redefines dependents picture x occurs 26 times. 

01 WORK-RECORu. \ 

02 NAME-FIELD PICTURE X. 

02 FILLER PICTJRE X VALUE IS SPACE. 

02 RECORD-Nu PICTURE 9999. 

02 FILLER PICTURE X VALUE IS SPACE. 

02 LOCATION PICTURE AAA VALUE IS "NYC". 

02 FILLER PiCTURE X VALUE IS SPACE. 

02 NO-OF-DEi'EMDENTS PICTURE XX. 

02 filler picture xm value is spaces. 

PROCEDURE DIVISION. 
DECLARATIVES. 
DEdUG-SECTION SeCTION. 

USE FOR DEBUGGING ON ALL REFERENCES OF ALP1A. 

IF OEBUG-COwTENTS = "D" OR "M" 
ADD 1 To DtBUG-SUB-1 

MOVE ALPHA! DEBUG-SUB-1) TO NAME-FIELD. 
END DECLARATIVE*. 
BEGIN. 

NOTE THAT ThE FOLLOWING OPENS THE OUTPUT FILE TO 3E SEATED 

AND INITIALIZES COUNTERS. 
STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT NOMBER. 

NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE 

CONTAINED 1 1* THE FILE, WRITES THEM ON TAPE, ANO DISPLAYS 

THEM ON THE CONSOLE. 
STEP-2. ADD 1 Tu KOUNT, ADO 1 TO NOMBER, MOVE ALPHA (KOUNT J TO 

NAME-FIELD. 

MOVE DEPEND (KOUNT) TO NO-OF-DEPENOENTS. 

MOVE NOMBER TO RECORD-NO. 
STEP-3. DISPLAY WORK-RECORO UPON C0NS3LE. WRITE RECDRD-1 FROM 

WORK—RECORD 
STEP-4. PERFORM* STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26. 

NOTE THAT TnE FOLLOWING CLOSES OUTPUT AND REOPENS IT AS 

INPUT. 
STEP-5. CLOSE FiLE-1. OPEN INPUT FILE-2. 

NOTE THAT TilE FOLLOWING READS BACK THE FILE AND SINGLES OUT 

EMPLOYEES WiTH NO DEPENDENTS. 
STEP-6. READ FIlE-2 RECORD INTO WORK-RECORD AT END GO TO STEP-8. 
STEP-7. IF NO-OF-UEPENDENTS IS EQUAL TO "0" MOVE "Z" TO 

NO-OF-DEPENuENTS. EXHIBIT NAMED WORK-RECORD. GO TO 

STEP-6. 
STEP-8. CLOSE FiLE-2. 

STOP RUN. 
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A 0001 
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C 0003 
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F 0006 
G 0007 
H 0008 
I 0009 
J 0010 
K 0011 
L 0012 
N 0013 
N 0014 
0015 
P 0016 
W 0017 
R 0018 
S 0019 
T 0020 
U 0021 

V 0022 
W 0023 

: X 0024 

Y 0025 
Z 0026 
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Figure 95. Program with OSS FOR DEBUGGING. 
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TBACE, EXHIBIT, AND ON 



Three additional debugging language 
statements are TRACE, EXHIBIT, and ON, Any 
one of these statements can be used as 
often as necessary. They can be 
interspersed 

throughout a COBOL source program, or they 
can be in a packet in the input stream to 
the compiler. 

Program debugging statements may not be 
desired after testing is completed. A 
debugging packet can be removed after 
testing. This allows elimination of the 
extra object program coding generated for 
the debugging statements. 

The output produced by the TBACE and 
EXHIBIT statements is listed on the system 
logical output device (SYSOOT) . If these 
statements are used, the SYSOUT DD 
statement must be specified in the 
execution time job step. 

The following discussions describe ways 
to use the debugging language. 



Following the Flow o f control 



The READY 
compiler gen 
paragraph na 
output unit 
point. The 
card numbers 
effect durin 
rather than 



TBACE statement causes the 
erated card numbers for each 
me to be listed on the system 
when control passes to that 
output appears as a list of 
If the VEBB option is in 
g compilation, paragraph-names 
card numbers will be displayed. 



To reduce execution time, a trace can be 
stopped with a RESET TRACE statement. The 
BBADY TBACE/RESET TBACE combination is 
helpful in examining a particular area of 
the program. The READY TBACE statement can 
be coded so that the trace begins before 
control passes to that area. The RESET 
TBACE statement can be coded so that the 
trace stops when the program has passed the 
area. The two trace statements can be used 
together where the flow of control is 
difficult to determine, e.g., with a series 
of PERFORM statements or with nested 
conditionals. 

Another way to control the amount of 
tracing, so that it is done conditionally, 
is to use the ON statement with the TBACE 
statement. When the COBOL compiler 
encounters an ON statement, it sets up a 
mechanism such as a counter that is 
incremented during execution whenever 
control passes through the ON statement. 
For example, if an error occurs when a 
specific record is processed, the ON 



statement can be used to isolate the 
problem record. The statement should be 
placed where control passes only once for 
each record that is read. When the 
contents of the counter equal the number of 
the record (as specified in the ON 
statement) , a trace can be taken on that 
record. The following example shows a way 
in which the processing of the 200th record 
could be selected for a TBACE statement. 

Col. 

1 8 

RD-REC. 



DEBUG 



RD-REC. 
PARA-NM-1. 



ON 200 BEADY TRACE. 
ON 201 RESET TRACE, 



If the TRACE statement were used without 
the ON statement, the processing of every 
record would be traced. 

A common program error could be either 

(1) failing to break a loop, or 

(2) unintentionally creating a loop. If 
many iterations of the loop are required 
before it can be determined that there is a 
program error, the ON statement can be used 
to initiate a trace only after the expected 
number of iterations has been completed. 

Notes ; 

1 . If an error occurs in an ON statement, 
the diagnostic message may refer to 
the previous statement number. 

2. When READY TRACE encounters a 
paragraph that is repetitively 
executed, it does not write out a 
separate record for each individual 
execution of the paragraph. Instead, 
it simplifies its output by keeping 
an internal count, and writing out a 
single summary record only when the 
paragraph iteration finally finishes. 
This record identifies the number of 
times the paragraph was executed. 
READY TRACE output is built to contain 
multiple paragraph entries on each 
print line. 

3 . In the event the paragraph iteration 
is a nonending loop, READY TRACE 
output does not include the current 
print line being built. Therefore, 
READY TRACE output never identifies 
the paragraph as having been entered 
at all. In the event of an ABEND, 
the last print line of READY TRACE 
data may not be printed. When either 
a non-ending loop or abnormal ending 
of a task occurs, the current print 
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line is available in the current 
SYSOUT buffer. 

Displaying Data Values duri ng Exec ution 



A programmer can display the value of a 
data item during program execution by using 
the EXHIBIT statement. The three forms of 
this statement display (1) the names and 
values of the identifiers or nonnumeric 
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literals listed in the EXHIBIT statement 
(EXHIBIT NAMED) whenever the statement is 
encountered daring execution, (2) the 
values of the items listed in this 
statement only if the value has changed 
since the last execution (EXHIBIT CHANGED) 
and (3) the names and values of the items 
listed in the statement only if the values 
have changed since the previous execution 
(EXHIBIT CHANGED NAMED) . The first time 
such a statement is executed, all values 
are considered changed and are displayed. 

]*2£<a: The combined total length of all 
items displayed with EXHIBIT CHANGED and 
EXHIBIT CHANGED NAMED cannot exceed 32,767 
bytes. The length of any one operand must 
be less than or equal to 256 bytes- The 
length of a "NAME" must be less than or 
equal to 120 characters. 

Data can be used to check the accuracy 
of the program. For example, the 
programmer can display specified fields 
from records, work the calculations 
himself, and compare his calculations with 
the output from his program. The coding 
for a payroll problem could be: 

Col. 

1 8 



GROSS-PAY-CALC. 

COMPUTE GROSS-PAY = 
RATE-PER-HOUR * (HRSWKD 
+ 1.5 * OVEBTIMEHBS) . 

NET-PAY-CALC. 



DEBUG NET-PAY-CALC 

SAMPLE-1. ON 10 AND 

EVERY 10 EXHIBIT NAMED 
RATE-PER-HO0R, HRSWKD, 
OVERTIMEHRS, GROSS-PAY. 

This coding will cause the values of the 
four fields to be listed for every tenth 
data record before net pay calculations are 
made. The output could appear as: 
RATE-PER-BOUR = 4.00 HRSWKD - 40.0 

OVERTIMEHRS = 0.0 GROSS-PAY = 160.00 
RATE-PER-HOUR = 4.10 HRSWKD = 40.0 

OVERTIMEHRS = 1.5 GROSS-PAY = 173.23 

RATE-PER-HOUR = 3.35 HRSWKD = 40.0 

OVERTIMEHRS =0.0 GROSS-PAY = 134.00 

llote: Decimal points are included in this 
example for clarity, but actual printouts 
depend on the data description in the 
program. 



The preceding is an example of checking 
at regular intervals (every tenth record). 
A check of any unusual conditions can be 
made by using various combinations of COBOL 
statements in the debug packet. For 
example: 

IF OVERTIMEHRS GREATER THAN 2.0 
EXHIBIT NAMED PAYRCOHRS 

In connection with the previous example, 
this statement could cause the entire pay 
record to be displayed whenever an unusual 
condition (overtime exceeding two hours) is 
encountered. 

The EXHIBIT CHANGED statement also can 
be used to monitor conditions that do not 
occur at regular intervals. The values of 
the items are listed only if the value has 
changed since the last execution of the 
statement. For example, suppose the 
program calculates postage rates to various 
cities. The flow of the program might be 
as shown in Figure 96. 



\ READ INPUT/ 
\ DATA FOR / < 
\ CITY / 



® 




L _ j 

Figure 96. Example of Program Flow 



Program Checkout 252.1 



The EXHIBIT CHANGED statement in the 
program could be: 

EXHIBIT CHANGED STATE CITY RATE 

The output from the EXHIBIT CHANGED 
statement could appear as: 



01 



01 


10 


02 


15 


03 




04 


10 


01 




02 


20 


03 


15 


04 




01 


10 



02 



03 



The first column contains the code for a 
state, the second column contains the code 
for a city, and the third columa contains 
the code for the postage rate. The value 
of an item is listed only if it is changed 
since the previous execution. For example, 
since the postage rate to city 02 and 03 in 
state 01 are the same, the rate is not 
printed for city 03. 

The EXHIBIT CHANGED NAMED statement 
lists the name of the data item and the 
value of that item if the value has 
changed. For example, the program might 
calculate the cost of various methods of 
shipping to different cities. After the 
calculations are made, the following 
statement could be in the program: 



EXHIBIT CHANGED NAMED STATE CITY RAIL 
BUS TRUCK AIR 



The output from this statement could appear 
as: 

STATE = 01 CITY = 01 RAIL = 10 
BUS = 14 TRUCK = 12 AIR = 20 

CITY = 02 

CITY = 03 BUS = 06 AIR = 15 

CITY = 04 SAIL = 30 BUS = 25 
TRUCK = 28 AIR = 34 

STATE = 02 CITY = 01 TRUCK = 25 

CITY = 02 TRUCK = 20 AIR = 30 



T^gjt|g2_.§-!?EQ<s[j:a-B- Selectively 



A debug packet allows the programmer to 
select a portion of the program for 
testing. The packet can include test data 
and can specify operations the programmer 
wants performed. When the testing is 
completed, the packet can be removed. The 
flow of control can be selectively altered 
by the inclusion of debug packets, as shown 
in Figure 97. 



i 1 
J START | 

I I 



\ 



I 

| STOP 
] RUN 
« 



1 

! 
V 

I 1 

J DEBUG | 
| PACKET | 
J FOR A | 
i , j 

I 



} DEBUG \ 
I PACKET | 
1 FOR C j 



Figure 97. Selective Testing of B 



Note that the name of the item and its 
value are listed only if the value has 
changed since the previous execution. 



In this program, A creates data, B 
processes it, and C prints it. The debug 
packet for A simulates test data. It is 
first in the program to be executed. In 
the packet, the last statement is GO TO B, 
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which permits A to be bypassed. After B is 
executed with the test data, control passes 
to the debug packet for C, which contains a 
GO TO statement that transfers control to 
the end of the program, bypassing C. 



T e sting changes and Additions to program s 



If a program runs correctly but changes 
or additions can make it more efficient, a 
debug packet can be used to test changes 
without modifying the original source 
program. 

If the changes to be incorporated are in 
the middle of a paragraph, the entire 
paragraph, with the changes included, must 
be written in the debug packet. The last 
statement in the packet should be a GO TO 
statement that transfers control to the 
next procedure to be executed. 

There are usually several ways to 
perform an operation. Alternative methods 
can be tested by putting them in debug 
packets. 

The source program library facility can 
be used for program checkout by placing a 
source program in a library (see 
"Libraries") . Changes or additions to the 
program can be tested by using the BASIS 
card and any number of INSERT and DELETE 
cards. Such changes or additions remain in 
effect only for the duration of the run. 



ABEND DUHPS 



If a serious error occurs during 
execution of a program, the job may be 
abnormally terminated; any remaining steps 
are bypassed, and a dump is generated. The 
programmer can use the dump for program 
checkout. (However, any pending transfers 
to an external device may not be completed. 
For example, if a READY TRACE statement is 
in effect when the job is abnormally 
terminated, the last card number may not 
appear on the external device.) In cases 
where the abnormal termination does not go 
to completion, a dump is not produced. 
This situation may cause duplicate name 
definition when the next job is run, and is 
discussed at the end of this section. 

If a SYSUDUflP DD statement has been 
included in the execution-time job step, 
the system will provide the programmer with 
a printout, in hexadecimal and EBCDIC 
format, of main storage. Those areas 
occupied by the problem program and its 
data at the time the error occurred, will 



be included. This printout is called an 
abnormal termination dump and in VS1 is 
identified by the heading 

*** ABDUMP REQUESTED *** 

If a SYS ABEND DD statement is specified, 
the contents of the nucleus is also 
printed. 

If neither a SYSUDUMP nor a SYSABEND DD 
statement is included in the execution-time 
job step, or its specification has been 
destroyed, an indicative durap is produced. 
This dump does not contain a printout of 
main storage and is not given under 0S/VS2. 

All dumps include a completion code 
designating the condition that caused the 
termination. The completion code consists 
of a system code and a user code, only one 
of the codes is nonzero. A nonzero system 
code indicates that the control program 
detected the error. 

The COBOL programmer can request dynamic 
dumps via a compile-time option. The 
SYMDMP option, requested in the PARM 
parameter of the EXEC statement, produces a 
symbolic formatted durap of the data area of 
the object program if the program 
abnormally terminates. . At execution time, 
the user can also request a dynamic dump at 
any point in the Procedure Division. 

Notes: 

• If a COBOL program abnormally 
terminates, then a formatted dump is 
produced for all COBOL programs 
compiled with the SYHDHP option which 
could include the abnormally 
terminating program and its callers, up 
to and including the main program. 

• The explanation of the system-generated 
completion codes and a complete 
description of the dumps are contained 
in the appropriate Deb u gg ing,, Guide. 
For a discussion of the COBOL symbolic 
debugging options, see the chapter 
entitled "Symbolic Debugging Features." 



USER-INITIATED DUMPS 



The COBOL programmer can cause a dump at 
any pre-specif ied point in his program by 
coding a call to the library subroutine 
ILBOABNO, in the following manner: 

77 COHP-CODE PIC S999 COUP. 



HOVE nnn TO COMP-CODE. 
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CALL »ILBOABN0» USING COMP-CODE. 

The three-digit number nnn will become the 
identifier in the Onnn user abend code 
produced with the resultant dump. 



in the file may be invalid. The 
compiler does not generate a test to 
check the sign position for a valid 
configuration before the item is used 
as an operand. 



ERRORS THAT CAN CAUSE A DUMP 



Following is a discussion of some error 
conditions that can cause a program to be 
abnormally terminated and a dump to be 
listed. 



Inp ut /Ou tput Error s 

Errors can occur while a COBOL file is 
being processed. For example, during data 
transmission, an input/output error may 
occur that cannot be corrected. In some 
situations, this will result in the job 
being terminated (see Figures 52 and 53) . 

Referring to an input area 

(non-VSAN/QSAM) before both an OPEN and a 
READ statement are issued can cause 
unpredictable results, because base locator 

(BL) cells and registers are not properly 
initialized. 

Another error that can cause termination 
is an attempt to read a file whose records 
are of a different size than those 
described in the source program. The 
section "Additional File Processing 
Information" contains more information 
about input/output errors. 



Erro rs Ca used by . In v alid D ata 



Abnormal termination of a job occurs 
when a data item with an invalid format is 
processed in the Procedure Division. 

Some of the program errors are: 

1. A data item in the Working-Storage 
Section is not initialized before it 
is used, causing invalid data to be 
picked up. 

2. An input file or received message 
contains invalid data or data 
incorrectly defined by its data 
description. For example, the 
contents of the sign position of an 
internal or external decimal data item 



4. 



6. 



7. 



If a group item is moved to a group 
item and the subordinate data 
descriptions are incompatible, the new 
data in the receiving field may not 
match the corresponding data 
descriptions. (Conversion or editing 
is not performed in a move involving a 
group item.) 

Note : A Numeric class test, "IF 
Numeric", for signed data items, 
allows C, D, and F as valid signs. 
For external decimal items this 
includes X'C1 ' through X'C9' and 
X'DT through X'D9' and X»F1 • through 
X'F9' as valid last bytes. For 
internal decimal items, this includes 
X'1C through X'9C , X 1 1D' through 
X'9D', and X'1F' through X ! 9F' as 
valid last bytes. Certain invalid 
numeric data items, such as EBCDIC A 
through R in the last byte of an 
external decimal numeric item, and 
EBCDIC <, * , % , 5) , ( , ) , _, ' , I 
1, ?, and " in the last byte of an 
internal decimal item, are considered 
valid numeric items for an "IF 
Numeric" test. 

The SIZE ERROR option is not specified 
for the COMPUTE statement and the 
result of the calculation is larger 
than the specified resultant 

COMPUTATIONAL data name. Using the 
result in a subseguent calculation 
might cause an error. 



The SIZE ERROR option is not specified 
for a DIVIDE statement, and an attempt 
is made to divide by zero. 



The USAGE specified for a redefining 
data item is different from the USAGE 
specified for the redefined item. An 
error results when the item is 
referred to by the wrong name for the 
current content. 



A record containing a data item 
described by an OCCURS clause with the 
DEPENDING ON data-name option, may 
cause data items in the record to be 
affected by a change in the value of 
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<l<lia-name during the course of program 
execution. This may result in 
incorrectly described data. 
Additional information about how to 
correct this situation is included in 
» Programming Technigues." 



The data description in the Linkage 

Section of a called program does not 

correctly describe the data defined in 
the calling program. 



9. Blanks read into data fields defined 
as numeric generate an invalid sign. 



10. Some common errors that occur when 
clearing group items in storage are: 

a. Moving ALL ZEROS to a group level 
item to clear several counters 
causes an invalid sign to be 
generated in all of the elementary 
fields except the lowest order 
field. 

b. Moving SPACES to a group level 
item will put invalid data in any 
numeric field in that group. 

c. Moving to a group level item 
moves one zero and pads the rest 
of the fields with blanks. 

11. Failure to initialize counters 
produces incorrect results. No 
initial values are generated by the 
compiler unless specifically 
instructed to do so with a VALUE 
clause. If such fields are defined as 
decimal , internal or external, invalid 
signs may result in addition to 
unpredictable initial values. If 
defined as binary, they will cause 
unpredictable results and, further, if 
used in subscripting, may exceed the 
range of the associated OCCURS clause 
and cause data to be fetched or stored 
erroneously. An addressing exception 
may occur if the uninitialized 
subscript generates a bad address. 

12. Not testing to insure that a subscript 
or index does not exceed the range of 
the associated OCCURS clause may lead 
to fetching and storing data from and 
to some incorrect locations. 

13. Failure to initialize an index 
produces incorrect results. No 
initial values are generated by the 
compiler unless a SET statement is 
executed. When indexing is then 
specified, the range of the OCCURS 
clause may be exceeded and cause data 
to be fetched or stored erroneously. 



An addressing exception may occur if 
the initialized index generates an 
address outside the range of the 
machine, or a protection exception if 
data is stored outside the partition 
of this program. 

14. A subscript or index set at zero will 
address data outside the range of the 
table. 

15. If either HIGH- VALUE or LOW-VALUE is 
moved to internal or external decimal 
fields and those fields are used for 
comparisons, computations, or 
subscripting, a data exception will 
occur. HIGH-VALUE and LOW-VALUE are 
the hexadecimal values X'FF* and 
X»00*, respectively (unless these 
values have been altered by a 

user- defined collating seguence) . 
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Additional I/O errors may occur that 
will result in an abnormal termination 
(these are listed below). For QSAM files, 
however, the user can employ the FILE 
STATUS clause to intercept many of these 
errors; his program can then identify and 
daal with them, and thus prevent the abend 
from occuring. 

1. No DD statement is included for a file 
described in the source program and an 
attempt is made to access the file. 
When an OPEN statement for the file is 
executed, the system console message 
is written. The programmer can elect 
to direct the operator to continue 
processing his program, but any READ, 
WRITE, REWRITE, or START associated 
with the unlocated file will fail. (A 
READ for a missing optional file, 
however, will follow end-of-file 
processing rules.) A similar 
situation exists when a file is closed 
WITH LOCK and an attempt is made to 
reopen it. 

2. A file is not opened and execution of 
a READ or WRITE statement for the file 
is attempted, or a MOVE to a record 
area in the file is attempted. 

3. A GO TO statement, with no procedure 
name following it, is not properly 
initialized with an ALTER statement 
before the first execution of the GO 
TO statement. 



4. Reference is made to an item in a file 
after end of data. This includes the 
use of the TERMINATE statement of the 
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Report Writer feature, if the CONTROL 6- In a blocked and/or multiple- buffered 
FOOTING r PAGE FOOTING, or REPORT file, information in a record is 

FOOTING contain items that are in the unavailable after a WRITE, 
file (e.g., SOURCE data-name, where 

data-name refers to an item in the 7. a READ is issued for a data set 
file) . referenced on a DD DUMMY statement. 

The AT END condition is sensed 
5. Block size for an F-format file is not 
an integral multiple of the record 
length. 
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immediately and any reference to a 
record in the data set produces 
unpredictable results. 

8- A STOP RUN statement is executed 
before all files are closed. 

9. A SORT did not execute successf ully. 
The programmer may check SORT-RETURN. 

10. An input/output statement is issued 
for a file after the AT END branch is 
taken, without closing and reopening 
the file. 

11. A SEND or RECEIVE statement is issued 
when a message control program is not 
running. 

12- A SEND or RECEIVE statement is issued 
for a QHAME (i.e., the M QNAME=" 
parameter of the DD card) that is 
unknown to the message control 
program. 



In addition to errors 
an abnormal termination, 
source program can occur 
of the program to be ove 
corresponding object cod 
become invalid. If an a 
to execute one of these 
abnormal termination may 
operation code of the in 
invalid, the instruction 
branch to an area contai 
instructions, or the ins 
a branch to an area outs 
such as an address prote 



that can result in 

errors in the 

that cause parts 
rlaid and the 
e instructions to 
ttempt is then made 
instructions, an 

result because the 
st ruction is 

results in a 
ning invalid 
truction results in 
ide the program, 
cted area. 



Some COBOL source program errors that 
can cause this overlaying are: 

1. Osing a subscript whose value exceeds 
the maximum specified in the 
associated OCCURS clause. 

2. Osing a data-name as a counter whose 
value exceeds the maximum value valid 
for that counter- 
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043 — Error occurred during the 

attempted opening of a TCAM 
application program data set, as 
described below. 



a. A value of 01 in register 
indicates the attempted opening of 
a TCAM application program data 
set without an active message 
control program (MCP) in the 
system. 

b. A value of 02 indicates that the 
QNAME= parameter of a DD statement 
associated with an input or output 
DCB for a COBOL program is not the 
name of a process entry defined in 
the terminal table. 

c. A value of 03 indicates that the 
process entry named by the QNAME= 
parameter of a DD statement 
associated with a COBOL program is 
currently being used by another 
COBOL program. 

d. A value of 04 indicates that 
insufficient main storage was 
available in the MCP to build 
internal control blocks associated 
with the COBOL program interface. 
Specify a larger region or 
partition si2e in the JOB 
statement for the MCP. 

e. A value of 05 indicates that 
insufficient main storage was 
available in the COBOL work area 
to build internal control blocks. 
Specify a larger region or 
partition size in the JOB 
statement for the COBOL program. 

3. 046 — Error occurred during the 

termination of the TCA8 MCP 
because the COBOL program data 
set was still open. Specify the 
STOP RON statement when COBOL 
processing is complete. Ensure 
that all COBOL programs have 
terminated processing before 
deactivating the MCP. 



The following cases represent some of 
the errors that can occur in a COBOL 
program and the interrupt or completion 
code associated with them. These errors do 
not necessarily cause an abnormal 
termination at the time they are recognized 
and do not always hold true. (See Appendix K 
for COBOL-initiated U-type completion codes.) 

1. 013 — Check register 2 of registers at 
the entry to ABEND. This address 
points to the DCB in conflict. 



0C1 — Operation Exception: 

a. Shen the interrupt is at 000048 or 
at 004800, look for a missing DD 
card or an unopened file. 

b. When the interrupt is at 000050, 
look at register 1 of the 
registers at entry to ABEND. Add 
hexadecimal 28 to the address 
found in register 1. This should 
point to the DD name of a missing 
DD statement. 
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c. Shen the interrupt is at 00004A, 
look for a missing card, i.e. , 



//SYSOUT DD SYSOUT=A 



any missing JCL card, or the wrong 
name of a JCL card. Add 
hexadecimal 28 to the address 
found in register 1 at entry to 
ABEND. This should point to the 
DD name of the DD statement in 
error. 

d. When interrupt is at 0Q004F, look 
for inconsistent JCL or check the 
system-name in the COBOL program. 



5. 0C4 — Protection Exception: 

a. Check for the block size and 
record size being egual for 
variable record input or output. 

b. Check for missing SELECT 
statement. 

c. If interrupt is at 004814, check 
for an attempt to READ an unopened 
input file or a missing DD card. 

d. Check for an uninitialized index 
or subscript. 

e. If a QSAM file with FILE STATUS 
opened OUTPUT, check for a missing 
DD card. 



6. 0C5 and 0C6 — Addressing and 

Specification Exception: 

a. Subscript or index value may have 
exceeded maximum and instruction 
or table area was overlaid. 

b. Check for an improper exit from a 
procedure being operated on by a 
PERFORM statement. 

c. Check for duplicate close of an 
input or output file if DS 
formatting discontinued. 

d. A sort is being attempted with an 
incorrect catalog procedure. 

e. Attempting to reference an 
input/output area before a READ or 
OPEN statement, respectively. 

f. Check for initialized subscript or 
index value. 



7. 0C7— Data Exception: 



a. Data field was not initialized. 

b. Input record numeric field 
contains blanks. 

c. Subscript or index value exceeded 
maximum and invalid data was 
referenced. 

d. Data was moved from the DISPLAY 
field to the COMPUTATIONAL or 
COMPUTATIONAL-3 field at group 
level. Therefore, no conversion 
was provided. 

e. The figurative constants ZERO or 
LOS-VALUE moved to a group level 
numeric field. 

f. Omission of USAGE clause or 
erroneous OSAGE clause. 

g. Incorrect Linkage Section data 
definition, passing parameters in 
wrong order, omission or inclusion 
of a parameter, failure to carry 
over a USAGE clause when 
necessary, or defining the length 
of a parameter incorrectly. 



8. 001 — I/O Error: 

a. Register 1 of the SVRB points to 
the DCB which caused the 
input/output problem. Look for 
input record and blocking errors. 
That is, the input does not agree 
with the record and blocking 
descriptions in the DCB, the COBOL 
file description, or the DD 
statement LRECL parameter. 

b. Attempted to READ after EOF has 
been sensed. 

c. Attempted to write to a QSAM file 
that has previously encountered 
end of file (taken a B3 7 exit) , 
and set the file status to X'34' 
and/or entered the INVALID KEY 
routine. 

9. 002 — Register 2 of registers at the 

entry to ABEND contains the 
address of the DCB for the file 
causing the input/output problem. 
Check the DCB list for the 
specific file. 

10. 013 — Error during execution of an OPEN 
EXTEND statement. Ensure that 
the system OPEN EXTEND facility 
is available. OPEN EXTEND 
reguires at least OS/VS1 Release 
6, or OS/VS2 Release 7 with S08. 
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11. 213 — Error during execution of OPEN 
statement for data set on mass 
storage device, as follows: 

a. DISP parameter of DD statement 

specified OLD for output data set, 
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12, 



13, 



14, 



15, 



b. Input/output error cannot be 

corrected when reading or writing 
the DSCB. Recreate the data set 
or resubmit the job. 



214 — Error during CLOSE for data set 

on tape; there is an input/output 
error that cannot be corrected 
either in tape positioning or 
volume disposition. Resubmit the 
job and inform the field engineer 
if error persists. 

237 — Error at EOV: 

a. Incorrect volume serial number 
specified in SER subparameter of 
VOLUME parameter of DD statement. 

b. Incorrect volume mounted. 

c. Incorrect labels. 

400 — If this completion code is 

generated during a compile step, 
the member to be compiled has not 
been extracted from the source 
library for compilation. 

413 — Error during execution of an OPEN 
statement for a data set on tape: 

a. Volume serial number was not 
specified for input data set. 

b. volume could not be mounted on the 
allocated device. 

c. There is an input/output error in 
reading the volume label that 
cannot be corrected. 



16. 
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17, 



806 — The error occurred during 
execution of a LINK, XCTL, 
ATTACH, or LOAD macro 
instruction. An error was 
detected by the control program 
routine for the BLDL macro 
instruction. The contents of 
register 15 indicate the nature 
of the error; 



08 An uncorrectable input/output error 
occurred when the control program 
attempted to search the directory 
of the library indicated as 
containing the requested program. 



18. 80A — Insufficient contiguous main 

storage for linkage to some phase 
of the compiler. The programmer 
should see if secondary data-set 
allocation has caused an extra 
DEB to be built at lower main 
storage addresses within the 
region. If so, this problem can 
be corrected by assigning 
sufficient primary extents for 
the data set in question. See 
"Data Set Requirements" for 
further information. If this 
error occurs when a non-COBOL 
program (such as IMS or an 
installation-defined assembler 
program) links to a COBOL load 
module many times in a job step, 
the programmer should determine 
if the NOENDJOB option was used; 
if so, specifying the ENDJOB 
option may correct the problem. 

19. 813 — Error during execution of an OPEN 

statement in verification of 
labels: 

a. Volume serial number specified in 

VOLOME parameter of DD statement 
is incorrect. 

b. Data set name specified in DSNAME 

parameter is incorrect. 

c. Wrong volume is mounted. 

20. 906 — The system use count limit was 

exceeded during the execution of 
a LINK, XCTL, LOAD, or ATTACH 
macro. If this error occurs when 
a non-COBOL program (such as IMS 
or an installation-defined 
assembler program) links to a 
COBOL load module many times in a 
job step, the programmer should 
determine if the NOENDJOB option 
was used; if so, specifying the 
ENDJOB option may correct the 
problem. 



Findin g Location of program, Interruption in 

COBOL Source, Program Using the Con densed 
Listing 



04 The requested program was not found 
in the indicated private, job, or 
link library. 



To determine the location of the 
interruption, the programmer should proceed 
as follows: 
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1. From first page of dump: 



Get completion code and program 
interruption storage location. 



b. Determine the starting address of 
the prograa (PRB address+20). 



2. From linkage editor listing: 

a. Determine storage address for each 
module. Add starting address of 
the program to origin of each 
module. 

b. Determine module in which 
interrupt storage location falls. 

c. Determine relative address. 
Subtract module storage address 
from interrupt location. 



No£e: The information in this section 
about the use of the abnormal termination 
dump applies only when running under 
0S/VS1. For information about the abnormal 
termination dumps under 0S/VS2, see the 
publication, 0S/YS2 Debugg ing, Guide. 



The abnormal termination dump provides 
the address at which the load module has 
been loaded (load address) and the address 
of the instruction that caused the 
interrupt. The programmer computes the 
load module area by adding the load address 
to the load module length, as shown in the 
linkage editor output, it is now possible 
to determine whether the instruction falls 
within the load module. If it does not, 
the interrupt could have resulted from an 
improper branch to a point outside the load 
module or an error occurring in another 
part of the system. 



3. From Procedure Division map: 

a. Find the highest previous relative 
address in the condensed listing. 
That statement is in error. 

b. Get line number and verb of COBOL 
source statement. 



If the instruction does fall within the 
load module, the programmer now determines 
in which part: the main program, a COBOL 
library subroutine, or a called prograa. 
The ranges of the various parts are 
determined by adding their relative 
origins, as shown in the linkage editor 
output, to the load address. 



4. From source listing find the line 
number and verb of source statement 
causing program interruption. 



USIHG THE ABNORMAL TERMINATION DUMP 



The programmer can also determine the 
cause of an abnormal termination with the 
following material: 



1. The COBOL program object code listing. 



A knowledge of the layout of the COBOL 
object module. 



The full abnormal termination dump in 
conjunction with the linkage editor 
map or cross reference list. 



A description of the linkage editor 
output and of the COBOL object code listing 
is found in "Output." Figure 91 shows the 
layout of the COBOL program object module. 



If the instruction occurred in an object 
module generated for a COBOL program, 
(i.e., the main program), the programmer 
can determine whether or not the 
instruction was one of the generated object 
code instructions. He can determine the 
address of the first instruction in the 
Procedure Division (as found in the object 
code listing) by adding its relative 
location to the location of the object 
module (load address plus relative origin). 
If it was one of the object code 
instructions, a similar technigue can be 
used to locate the exact instruction. If 
it was not one of these instructions, the 
error has occurred in another part of the 
object module. Control possibly went there 
because of an improper branch. 
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The following general rules can be used 
to deter mine the cause of the dump and the 
error. 



Determine the COBOL statement that 
generated the code leading to the 
program check. 

a- The top of the system dump will 
tell the address of the PC 
(Program Check) instruction and 
the type of PC. Locate the 
instruction in the core dump. 

b. Determine the relocation factor of 
the program from the linkage 
editor map. subtract the 
relocation factor from the address 
of the invalid instruction. 

c. The address that results may be 
located in the procedure division 
map generated by the HAP option. 
(The coding shown at this location 
of the map should correspond to 
the instruction located in step 
one.) 

d. Preceding the address and code 
found in step three, find the 
sequence number of the 
corresponding COBOL statement in 
the listing and the number of the 
element in the sentence that 
generated the code. 



Be sure the COBOL statement is coded 
properly. 



If the statement is coded properly, go 
back to the main storage dump and 
determine the type of PC. 
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If one or both of the fields 
being operated on are defined as 
external decimal, the programmer 
will find one or more pack 
instructions immediately ahead of 
the PC instruction. From these 
determine the address of the 



external decimal field that 
generated the invalid sign. 
Several common causes of data 
exceptions are given in "Errors 
Caused by Invalid Data." 

b. If it is a protection exception, 
one possible cause is that a base 
register used in the instruction 
has not been initialized. Base 
registers in COBOL are initialized 
at different times. For QSAfi and 
VSAM input files the register is 
initialized at OPEN; for other 
input files, the register is not 
initialized until the first 
successful read. For output 
files, the registers are 
initialized during the processing 
of the OPEN statement. When faced 
with a protection exception, the 
programmer should go to the COBOL 
source program to ascertain that 
no data has been moved prior to 
the time when base registers are 
initialized. 

c. If an addressing or specification 
exception occurs, the programmer 
may find upon inspection (but not 
always) that registers have been 
unexpectedly modified and the 
problem becomes one of finding out 
how. Two possible approaches are: 

(1) Check the addresses in 

registers 14 and 15 against 
the address of the PC 
instruction. If the address 
of the PC instruction is equal 
to or slightly larger than the 
address in register 15, the 
address probably is in a 
subroutine, and the address in 
register 14 should be the 
return address. A BAL or BALR 
instruction probably will 
precede the return address. 
The programmer should look for 
this particularly when the 
problem is not with a COBOL 
statement. If the PC 
instruction has an address 
equal to or a bit larger than 
the address in register 14, 
then the programmer probably 
has just returned from a 
subroutine, and register 15 
should still be pointing to 
the entry address of the 
subroutine. The programmer 
should check the coding to see 
if this could reasonably be 
so, and check the entry points 
listed on the linkage editor 
map. If this approach bears 
further action, a listing of 
the subroutine would be needed 
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(2) 



or the instructions from the 
dump must be interpreted. 

If the foregoing step does not 
locate the error, the 
programmer should check back 
through the dump to see what 
exists between the PC 
instruction and the last 
unconditional branch in order 
to determine the possible 
course of events. 
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In that example, the completion code in 
the dump, (?) , indicates the condition 
causing the abnormal termination. If the 
system part of the code is nonzero, the 
explanation can be found in the appropriate 
Debugging Guide. In the program ABEND, the 
completion code is 0C7; invalid data is the 
reason for termination. 



Debugging the Program 

Suggested below are general procedures 
for locating and correcting the source 
statement responsible for abnormal 
termination. 

1. The INTESSUPT hhhhhh entry, (f) , gives 
the hexadecimal address of the 
instruction following the instruction 
that initiated the interrupt and 
caused the dump. This address can be 
used to determine the relative 
location of the instruction in the 
load module (see item 4 below) . 

2. To determine the main storage area 
occupied by the load module, add the 
total length of the module, in 
hexadecimal format, to its load 
address. The load address can be 
obtained from the EPA entry, (5) , of 
the CDE specification. The last six 
digits of this entry are the address 
of the entry point <INIT1) in the 
COBOL program. 

The total length of the load module 
is indicated in the TOTAL LENGTH 
entry, (§) , in the linkage editor 
output. The highest location in the 
load module is: 

<D ♦ ® 



Thus, the range is from (3) to 
(3) ♦ ®. Since the address (2) falls 
within this range, the instruction 
initiating the dump must be within the 
load module. 

3. To determine the relative location 
within the load module of the 
instruction indicated in the INTERRUPT 
entry, subtract the load address from 
the address of the instruction. 

4. To determine whether or not the 
instruction occurred in the object 
module generated for the program, 
compare its relative location (2) - (3) 
with the total length, (§) , of the 
object module. If the relative 
location were greater than the size of 
the object module, then the error 
would not be part of this program. A 
relative location between the size of 
the object module/ Q) , and the total 
length © would indicate that the 
abnormal termination had occurred in 
one of the COBOL library subroutines. 
Such an error could be located by 
comparing the relative location with 
the relative origin of the subroutines. 
In this example, © - (2) is less than 
the object module size (5) , so the 
instruction occurred in the main 
program. 

5. To determine whether or not the 
abnormal termination occurred in one 
of the object code instructions 
generated as a result of a statement 
in the Procedure Division of the 
source program, compare its relative 
location with the relative location of 
the first generated instruction in the 
Procedure Division, @ . In this 
example, the relative location of the 
instruction is greater than that of 
the first generated instruction and so 
it can be found by locating the 
corresponding relative location. The 
immediately preceding object code 
instruction then is the instruction 
that initiated the dump, (?) . In this 
example, it is an instruction 
generated as a result of a COMPUTE 
statement. Checking back to the 
source program listing, the 
corresponding statement 18,® , is 
located and ' B* is seen to be the 
data-name that caused the trouble. 
Data item B is defined in the Data 
Division, (9) , as a COMPUTATIONAL- 3 or 
internal decimal item, but the value 
at B is there as a result of a VALUE 
clause for A, the item that B 
redefines. This value is in external 
decimal format since there is no USAGE 
clause specified. The configuration 
of A is invalid for B and results in 
an interrupt. 
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De termining the L ocation of an ABEND When 
Running Dynamically: When running 
dynamically, the programmer should do the 
following to determine whether the abend 
occurred in the main program. 

1. Figure 99 is a Load List of the same 
program shown in Figure 98, but 
compiled with the DYNAM option. The 
compiler produces a Load List that 
contains the COBOL subroutine library 
names and the addresses used in the 
program. These are anything beginning 
with ILBO. ® The programmer is 
particularly interested in any ILBO 
subroutine that does not end in a 



zero, such as ILBORNT, ILBOREC, 
ILBODSP, etc. 



In this case, the abend has occurred 
at (D) . To determine whether this is 
within the main program, go to the 
Load List, and look for the subroutine 
with its address closest to that of 
the abend, which is at (B) • 

Look below to the second part of the 
Load List. This contains the length 
of the subroutines that begin at the 
address specified above. In this case 
at (§) , under the LN column, the 
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00001 


00001 


CCCC2 


00002 


00003 


00003 


CGCC4 


00004 


0OCC5 


000C5 


0GCC6 


00006 


00007 


00007 


00CC8 


00008 


0CCC9 


00009 


C0C1C 


00010 


OOOii 


0Q011 


oooia 


00012 


CCC13 


00013 


CO 014 


00014 


00C15 


00015 


C0C16 


00016 


O0C17 


00017 


OOCld 


00018 


OOCAs 


00019 



IDENTIFICATION DIVISION. 
PROGRAM-ID. AdEi.0. 
REMARKS. 

THIS IS A PROGRAM TO ILLUSTRATE THE ABNORMAL 
TERMINATION OF A PROGRAM. 
ENVIRONMENT DIVISION. 
CONFIGURATION ScCTION. 
SOURCE-COMPUTER. I6M-370-168. 
OBJECT-COMPUTER. IfaM-370-168. 

OATA DIVISION. 

WORKING-STORAGE SECTION. 
01 RECOROA. 

02 A PICTUKE S9(4) VALUE 1234. _. 

02 B KEDEFiNtS A PICTUKE S9(7J COMPUTATI ONAL-3. (jj 
PROCEDURE DIVISION. 

COMPUTE B = B + 1. (?) 

STOP RUN. ^^ 



INTRNL NAME LVL SJURCc NAME 

DNM=1-j32 01 RECORliA 

DNM=1-li52 02 A 

DNM=l-u63 02 B 



8ASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE 


BL=1 


000 


ONM= 1-032 


OS 0CL4 


GR3UP 


6L=1 


000 


ONM=1-052 


DS *C 


DISP-NM 


BL = 1 


000 


DN*l=l-063 


DS 4P 


CPMP-? 



MEM0K1T MAP 




TGT 


000A8 


SAVE AREA 


000A8 


SWITCH 


OOOFO 


TALLY 


0O0F4 


SORT SAVE 


000F8 


ENTRY-SAVE 


OOOFC 


SORT CORE SIZE 


00100 


RET CODE 


00104 


SORT RET 


00106 


WORKING CELLS 


00108 


SORT FILE SIZE 


00238 


SORT MODE SUE 


0023C 


PGT-VN TBL 


00240 


TGT-VN TBL 


00244 


RESERVED 


00248 


UNCTL CELLS 


O02C0 


PFMCTL CELLS 


002C0 


PFMSAV CELLS 


002C0 


VN CELLS 


OO2C0 


SAVE AREA =2 


002C0 


SAVE AREA =3 


002C0 


XSASW CELLS 


002CO 


XSA CELLS 


002C0 


PARAM CELLS 


002CO 


RPTSAV AREA 


002C0 


CHECKPT CTR 


002C0 



LITEKAL PCOL I HEX) 
0C2C0 (LIT+Oi 1C 



PGT 

OVERFLOW CELLS 
VIRTUAL CELLS 
PROCEDURE NAME CELLS 
GENERATEO NAME (.ELLS 
DCB ADDRESS CELLS 
VNI CELLS 
LITERALS 
DISPLAY LITERAL* 



002C0 

002C0 
002C0 
002CC 
002CC 
002D0 
0O2D0 
002D0 
002D1 



REGISTER ASSIGNMENT 
REG 6 BL =1 
ttORKING-STORAut STARTS AT LOCATION 030 AO FOR A LENGTH OF 00008. 



Figure 98. COBOL Program That will Abnormally Terminate (Part 1 of 3) 
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Id 


COMPOTE 000202 


© 




000202 


F8 70 208 C 010 




000208 


FA 43 20B 6 000 




00020E 


F8 33 6 000 20C 


19 


STOP 0002 E4 






0002E4 


58 FO C 008 




0002E8 


07 FF 




0002EA 

• 


50 DO 5 008 




• 

0000 oc 


Cii.2C5D5C4404040 




000014 


E5c2D9Fl 




000018 


07 00 




0000 1A 


98 9F F 024 




0000 IE 


07 FF 




000020 


96 02 1 034 




000024 


07 FE 




000026 


41 FO 001 




0C002A 


07 FE 




00002C 


00u0032A 




OC0030 


OOuOOOOO 




000034 


OOoOOOOO 




000038 


0Ou002C0 




C0003C 


OOuOOOA8 




000040 


00u002D2 




000044 


00o002EA 




000048 






000084 


OOuOOOOO 




000088 


Flh24BF4F248F5F2 




000090 


Clc4C740FlF66B40 




000098 


F1F9F7F6 


♦STATISTICS^ SOURCE RECORD^ 19 D 


♦OPTIONS 


IN EFFECT^ SIZE = 131072 BUF = 


♦OPTIONS 


IN EFFECT^ 1 


JMAP, PMAP, NOCLI 


♦OPTIUNS 


IN E^FECT^ NOTERM, NONUM, NOBATC 


♦OPTIONS 


IN EFFECT^ NOOPTlMlZt, NOSYMOMP, 


♦OPTIONS 


IN EFFECT^ NOLST , NUFDEC K.NOCDE 


♦OPTIONS 


IN EI-FECT+ NOCOUNT, NOVBSUM, NOV 



START 



© 



GN=01 



INIT2 



EQU 


* 


ZAP 


208(8,131,010(1,12) 


AP 


20B(5,13), 000(4, 61 


ZAP 


000(4,6),20C(4,131 


EQU 


4c 


L 


15,008(0,12) 


BCR 


15,15 


ST 


13,008(0,5) 


OC 


X , C1C2C505C4404040« 


DC 


X'E5E2D9F1« 


BCR 


0,0 


L* 


9,15,024(15) 


BCR 


15,15 


01 


034(11, X«02' 


BCR 


15,14 


LA 


15,001(0,01 


BCR 


15,14 


AOCON 


L4UNIT31 


ADC ON 


L4(INIT1) 


AOCON 


L4UNIT1) 


ADCON 


L4(PGT) 


A DC ON 


L4(TGT1 


ADCON 


L4(START1 


ADCON 


L4(INIT21 


DS 


15F 


DC 


X« 00000000' 


DC 


X , F1F248F4F24BF5F2« 


DC 


X«C1E4C740F1F66B40' 


DC 


X»F1F9F7F6« 



TS=01 
TS=04 
DNM=l-53 

V(ILBOSRVl) 



LIT«-0 

DNM=l-63 

TS=04+1 



Ffc4-LEVEL LINKAGE EDITOR OPTIuNS SPECIFIED LIST , LET , XREF 
OfcFAULT OPTION(S) UScO - SIZE= ( 196608, 65536) 



CROSS REFERENCE TABLE 



CCNTROL SECTION 




ENTRY 
















NAME 


OKIGIN 


LENGTH (?) 


NAME LOCATION 


NAME LOCATION 


NAME LOCATION 


1 M*MF 


L03t\TI0 


ABEND 


00 


390 


















ILBOCOMO^ 


390 


169 


ILBOCOM 


390 














ILBOSRV ♦ 


500 


48E 
























ILBOSRVO 


50A 


ILB0SR5 


50A 


ILB0SR3 


50A 


ILB3SR 


50A 








ILB0SRV1 


50E 


ILB0STP1 


50E 


ILBOST 


512 


ILBOSTPD 


512 


ILBOBEG ♦ 


990 


128 


ILBOBEGO 


992 














ILfiOCrtM ♦ 


AB8 


38B 


ILBOCMMO 


ABA 


ILB0CMM1 


ABE 










ILeOMSG ♦ 


E48 


F2 


ILBOMSGO 


E4A 














LCCATION . 


RcFERS 


TO SYMBOL iN 


CONTROL SECTION 




LOCATION 


REFERS 


TO SYMBOL IN 


CCNTROL SECTION 




2C0 




ILBOSRVO 


ILBOSRV 




2C4 




ILB0SR5 




ILBOSRV 




2C8 




ILB0SRV1 


ILBOSRV 




260 




ILBOCOMO 




ILBOCOMO 




850 




ILBOCJM 


ILBOCOMO 




854 




ILBOCMMO 




ILBOCMM 




858 




ILBGBEGO 


ILBOBEG 




85C 




ILBOMSGO 




ILBOMSG 




860 




ILB0SND2 


$UNRESOLVEO(W) 
















ENTRY ACDRESi 


00 



















TCTAL LENGTH F40 (J) 
^♦♦*GU OOES NOT EXIST BoT HAS BEEN ADDED TO DATA SET 
ALTHQkIZATION CODE IS o. 



Figure 98. COBOL Program That sill abnormally Terminate {Part 2 of 3) 
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JCE ABEND STEP GO 

COMPLETION COi/t SYSTEM = oC7 (7) 

PSW AT ENTRY TO ABEND 078D20UO 0007539E 



TIME 124329 DATE 76229 



ASC8 00FE8A28 



ASCB 

10SP 

LUA 

cfclST 

DUMP 

VSC 

uuCB 

MCC 

iMCT 



C1E2C3C2 
OOOCOOOO 
007FF548 
89737A1F 
007FF008 
00000039 
00FE89C8 
00000000 
OCOOOOOO 



TCB 7D3128 KBP 007FD9D0 



007FC5A8 
01074F80 
00000000 
007FD04C 
00000000 
007D3250 
TMSAV 00000000 
nID E3C3C240 
KPT 00000000 
EVENT 00000000 



MSS 

t-SA 

LTC 

iTAB 

kESV 

cXT2 



FWUP 

SPL 

RSM 

XWST 

FK1 

TCBS 

OUXB 

JBNI 

SWTL 

HIE 



00FE7E68 
00FE8AF8 
00FE88E8 
02235000 
FFFFOOOO 
00000001 
00FF2A48 
00FE8370 
00001410 

00000000 



PK-FLG 80010000 
TCB OOOOOOOO 

00000000 
807FC960 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 



IQE 

TCT 

iOBRC 

AECB 

aBCR 

KT*i 

oBTB 

kESV 



BWDP 
CPUS 
CSCB 
JSTL 
TMCH 
LOCK 
FMCT 
JBNS 
SRBT 

DEB 

FLG 

TME 

ECB 

USER 

XCPD 

RESV 

RESV 

ESTA 

SWAS 

RESV 



00FE6B08 
00000001 
00FE8B10 
000001 IE 
OOOOOOOO 
OOOOOOOO 
00240000 
OOFE8B20 
OOOOOOOO 

007D8798 
OOOOFFFF 
OOOOOOOO 
007C8174 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
007D9F30 
OOOOOOOO 



CMSF 

IDSQ 

TSB 

ECB 

ASXB 

LSQH 

XMPQ 

LGCB 

ATME 



OOOOOOOO 
001EO0O* 
OOOOOOOO 
807FD790 
007FF300 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
03336000 



TIO 007C0020 
LLS 007D3B40 
JST 007D3128 
TSF 20000000 
SD.F OOOOOOOO 
EXT OOOOOOOO 
BAK 007FCAOO 
FOE OOOOOOOO 
UKY 007C8600 
SCB OOOOOOOO 
RES OOOOOOOO 



SVRB 
IODP 
EJST 
USET 
SWCT 
QECB 
IQEA 
VGTT 



OOOOOOOO 
E242307B 
OOOOOOOO 
8973742F 
D2570000 
OOOOOOOO 
00033003 
00033030 



CMP 

JLB 

NTC 

D-PQE 

1DID 

BITS 

RTMWA 

SWA 

CPVI 

GTF 

RESV 



930C7330 
007C8A50 
OOOOOOOO 
007FF548 
OOOOOOOO 
03000303 
007DEC98 
007DCD50 
0040FFFF 
OOOOOOOO 
03000333 



SYNC 
STOR 
XJST 
QSCV 
SSP.B 
MECB 
RTHA 
PCTT 



PAGE 0001 



OOOOOOOO 
OF180:00 
1D737000 
001FF630 
33033333 
*3000000 
03000000 
03003300 



TPM 

jpa 

OTC 

AQE 

JSC8 

DAP 

I OT* 

RESV 

BYTl 

SVAB 

RESV 



OOOOOOOO 
OO703*E0 
OO7FCA00 
D07C8C13 
007FBF84 
00300000 
OOOOOOOO 
OOOOOOOO 
*83if0033 
OOOOOOOO 
OOOOOOOO 



ACTIVE RBS 



7C9F98 KESV 
rLGl 



SVRB 7FD900 



OOOOOOOO 
OOOOOOOO 
KESV OOOOOOOO 
w/TTR OOOOOOOO 
kG 0-7 007D3B50 
KG 8-15 007C8150 

KESV OOOOOOOO 
FLG1 20000000 
KESV OCOOOOOO 
g/TTR OOOOOOOO 



RcSV OOOOOOOO RTPSW1 07802000 
Wo-L-IC 00060007 

APSW OOOOOOOO S2-STAB 00110082 

WT-LNK 007D312 8 

00074FF8 00000040 007F26F4 

0O7FCFE0 



0007539E RTPSW2 00060007 0007C0C0 



FL-CDE 007034EO PSW 078D2000 



807FC960 



OOOOOOOO 



007F26D0 
70DCA602 



007F:AOO 
00074FBO 



O07CO018 
40DCA8FC 



KESV OOOOOOOO RTPSW1 OOOOOOOO C 

WC-L-IC 00020033 

aPSW OOOOOOOO SZ-STAB 0019D022 

wT-LNK 007C9F98 



RTPSW2 00030000 



FL-CDE OOOOOOOO PSK 370T1033 



KG 0-7 
KG 8-15 
eXTSA 



OOOOOOOO 
00075370 
OOOOOOOO 
0O7DEC98 
OOOOOOOO 



50075432 
000753EA 
50075432 
FF000368 

00000030 



00000040 
000750C0 
00018C30 
40000101 
OOOOOOOO 



007F25F4 
000750CO 
007D3128 
900C7000 
OOOOOOOO 



003753A4 
00075380 
007FD900 



50075416 
00375168 
00FE8A28 



00075160 
03075392 
0003AA64 



FDO 00300 
007:8180 



0007536F 
533753EC 
OOOOOOOO 



OOOOOOOO RESV 



LOAC LIST 

NE OOuOOOOO RSP-CDE U0FE7660 CNT 00010001 



© 



7D34E0 
FE7660 



NCDE OOOOOOOu 
NCDE 00FEE47J 



R9P 007C9F98 NM GO 

RBP OOOOOOOO NM IGG0190K 



EPA 000750CO 
EPA 00F2A000 



XL/MJ 007C3000 
XL/MJ 00FE7680 



JSE 00013030 
USE 00033033 



ATTR 0B20000 
ATTR P322300 



SAVE AREA TRACE 

GC HAS cNTERED VIA LINK 



«01 OOOOOOOO 
Ki 00074FF8 
K7 FDOOOOOO 

WD1 OOOOOOOO 
Kl OOOOOOOO 
K7 OOOOOOOO 



HSa OJOOOOOO LSA 00075168 RET 00018C80 EPA 000750CO RO 007D3B50 

R2 00000040 R3 007F26F4 R4 0O7F26D0 R5 007FCA00 R6 007C0018 

R8 007C8150 R9 807FC96O RIO OOOOOOOO Rll 007FCFE0 R12 70DCA632 

HSa 00O74FB0 LSA OOOOOOOO RET OOOOOOOO EPA OOOOOOOO RO OOOOOOOO 

R2 OOOOOOOO R3 OOOOOOOO R4 OOOOOOOO R5 00000003 P6 00033033 

R8 OOOOOOOO R9 OOOOOOOO RIO OOOOOOOO Rll OOOOOOOO R12 OOOOOOOO 



INTERRUPT AT 07539c (7) 



PRCCEtOING 8Ai.K VIA REG 13 

SA 075168 «D1 OOOOOOOO HSa 00074FBO LSA OOOOOOOO RET OOOOOOOO EPA OOOOOOOO 
Kl OOOOOOOO R2 OOOOOOOO R3 OOOOOOOO R4 OOOOOOOO R5 OOOOOOOO 
K7 OOOOOOOO R8 OOOOOOOO R9 OOOOOOOO RIO OOOOOOOO Rll OOOOOOOO 

GO WAS ENTERED VIA LINK 

REGS AT ENTRY TO ABEND 



RO OOOOOOOO 
P6 00000003 
R12 OOOOOOOO 



OOOOOOOOOOOuOOOO 



0000000000000000 



0000000000000000 



0000000000000000 



REGS 0-7 
REGS 8- la 



OOOOOOOO 
00075370 



S0075432 
u00753EA 



00000040 
0C0750C0 



007F26F4 
00075 OCO 



000753A4 
00075380 



50075416 
00075168 



0007516 
00075392 



0007536F 
500753EC 



LOAC MODULE 



GO 



C15CC0 90ECUOOC 135D05F0 45tiuF010 C1C2C5D5 

C75CE0 9602J.034 07FE41F0 0O0j.07FE 000753EA 

C "if ICG 0007a392 000753AA OOOoOOOO OOOOOOOO 

75120 OOOOOOOO OOOOOOOO OOOuOOOO OOOOOOOO 

C75140 OOOOOOOO OOOOOOOO F1F<:4BF4 F24BF5F2 



C4404040 E5E2D9F1 0700989F F02407FF 

000750CO 0O0750C0 00075380 00075168 

OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 

OOOOOOOO OOOOOOOO OOOOOOOO 00000003 

C1E4C740 F1F66B40 F1F9F7F6 OOOOOOOO 



* O..O.ABEN0 VSR1....C 

* 

*....... 

*.................... 

* 12.42.52AUG 16. 1976. 



Figure 98. COBOL Program That Sill Abnormally Terminate (Part 3 of 3) 
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NE 007BE6E8 
NE 007CA008 
NE OOuOOOOO 



RSP-CDE uOFC3558 
RSP-COE J07BE918 
RSP-CDE «07CAE30 



CNT OOO1OO01 
CNT 00010000 
CNT 00010000 



NE 007BE8F8 
NE 007CHE20 



RSP-COE 307BE6F8 
RSP-COE 007BE958 



CNT 00010000 
CNT 00010033 



7FC860 
FC3558 
7BE6F8 
7BE718 
7BE918 
7BE938 
7BE958 
7BE978 
7CAE30 
7CAE50 



7FC240 
FC3578 
7BE8E8 
7BE908 
7CA1B0 
7FCC90 



CEB 

702780 
7D27AO 
7027CO 
7O27E0 

7D2800 



NCDE 
NCOE 
NCDE 
NCDE 
NCDE 
NCDE 
NCDE 
NCDE 
NCOE 
NCDE 



OOOOOOOu 
00FC312J 
007BE93t) 
007BE6F<j 
007BE97o 
007BE91o 
007CAE5U 
007BE95o 
007FCB60 
007CAE3O 



RBP 
RBP 
RBP 
RBP 
RBP 
RBP 
RBP 
RBP 
RBP 
RBP 



007CA5C8 
00000000 
007FD900 
00000000 
007FD900 
00000000 
007FD900 
00000000 
007FD900 
00000000 



NM GO 

NM IGG0190K 

NM 

NM 

NM 



LBOSR 

ILBOSRV 

ILBOCMMO 

ILBOCMM 

ILBONTRO 

ILBONTR 



EPA 00075BE8 
EPA OOF2AO00 



EPA 000755F2 
EPA 000755E8 
EPA 0007611A 
EPA 00076118 
EPA 000764AA 
EPA 000764AA 



XL/MJ 
XL/MJ 



XL/MJ 
XL/MJ 
XL/MJ 
XL/MJ 
XL/MJ 
XL/MJ 
XL/MJ 
XL/MJ 



007FC240 
00FC3578 



SZ 00000010 
SZ 00000010 
SZ 00000010 
SZ 00000010 
SZ 00000010 
SZ 00000010 



C87D*DD0 OF000900 
00240000 D1C5E2F2 
E2E2U6C2 00140010 
0C7D<:798 OO7D4DD0 



NO 00000001 
NU 00000001 
NO 00000001 
NU 00000001 
NU 00000001 
NO 00000001 



000*0000 007DFE68 
OOOoOOOO 00000000 
007U27BC 00000000 
OOOoOOOO 00000000 




007BE718 
007BE8E8 
037BE938 
007BE908 
007BE978 
007CA1BO 
007C4E50 
007FCC90 



USE 
USE 



USE 
USE 
USE 
USE 
USE 
USE 
USE 
USE 



OOOIOOOO 
00010000 



00330033 
OOOIOOOO 
00000000 
OOOIOOOO 
00000000 
00013030 
00000000 
OOOIOOOO 



ATTP 
ATTR 



OB20000 
B072000, 



ATTR 1710000 

ATTP 1320000 

»TT* 3710000 

ATTR 3320000 

UTR 3710000 

ATT* 3320000 

ATTR 1710000 

ATTH 1320000 



~® 



007D2810 10810001 007BE528 00000000 

8F074D30 O0E712CC 00302C38 E2E2C9C2 

00000000 00000000 00000000 00000000 

007D27F4 00180000 00000000 007D2934 



* V * 

* X SSIB* 

*....JES2 * 

*SSOB 4 * 



SAVE AREA TRACE 

GO WAS tNTERED VIA LINK 



074FB0 «D1 00000000 
Kl 00074FF8 
k7 FDOOOOOO 

075C90 teDl 00000000 
kl OOOOOOOO 
K7 00000000 



HSA oooooooo 

R2 00000040 
R8 007FC028 

HSA 00074FBO 
R2 00000000 
R8 00000000 



LSA 00075C90 
R3 007F26F4 
R9 807FC960 

LSA 00000000 
R3 00000000 
R9 OOOOOOOO 



RET 00018C80 
R4 007F2600 
RIO OOOOOOOO 

RET OOOOOOOO 
R4 OOOOOOOO 
RIO OOOOOOOO 



EPA 00075BE8 
R5 0O7FCAO0 
Rll 007FCFA0 

EPA OOOOOOOO 
R5 OOOOOOOO 
Rll OOOOOOOO 



PO 007FCCAO 

P.6 007D6018 

R12 70DCA602 

RO OOOOOOOO 

R6 OOOOOOOO 

R12 00030000 



INTERRUPT AT u75ED6 



-£) 



Figure 99- Load List of Program That Hill Abnormally Terminate 
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length of the subroutine is at © - 
Adding the length of the subroutine (c) to 
the starting address (§) , results in a 
number falling within the confines of the 
main program. 

4. After this is determined, the 

programmer continues his debugging in 
the specified manner. 



Finding Data Records in an Abnormal 
Termination Dump 



The glossary, lis 
option is specified, 
about all data-names 
source program. The 
given data-name may 
BL number and displa 
that entry in the gl 
locating the appropr 
TGT. The hexadecima 
displacement and the 
should give the rela 
area desired. This 
absolute address as 
associated with Figu 



ted when the DMAP 
contains information 
described in the COBOL 
location assigned to a 
be found by using the 
cement specified for 
ossary, and then 
iate BL cell in the 
1 sum of the glossary 
contents of the cell 
tive address of the 
can be converted to an 
described in the text 
re 98. 



Since the sample problem program shown 
in Figure 100 was interrupted because of a 
data exception, the programmer should 
locate the contents of field B at the time 
of the interrupt. The numerals encircled 
in the two techniques given below refer to 
information similarly labeled in the sample 
program. 

Osin q the General Register s: The general 
registers usually contain information that 
can be helpful to the programmer who is 
trying to locate specific data. 

1. Locate data-name B, (?) , in the 
glossary. It appears under the column 
headed SOURCE- NAME. Source-name B has 
been assigned to base locator 3 (i.e., 
BL=3) with a displacement of 058. The 
sum of the value of base locator 3 and 
the hexadecimal displacement value 58 
is the address of data-name B. 

2. The Register Assignment table, (g) , 
lists the registers assigned to each 
base locator. Register 6 has been 
assigned to BL=3. 

3. The contents of the 16 general 
registers at the time of the interrupt 
are displayed at the beginning of the 



dump 



aispj 
. 0) 



The location of data-name B, (5) 
now be determined by adding the 



can 



contents of register 6 and the 
hexadecimal displacement value 58. 
The result is the address of the 
leftmost byte of the 4-byte 
field B. Field B contains F1F2F3C4. 
This is external decimal 
representation and does not correspond 
to the OSAGE COMP0TATIONAL-3 defined 
in the source listing. 

Psing the,T g T Memory Map: If the general 
registers appear not to contain meaningful 
information, it may be that errors in the 
problem program have destroyed their 
contents. In such a case, the alternate 
method of locating data-names given below 
should be helpful. 

1. The location assigned to a given 
data-name may also be found by using 
the BL CELLS relocation value given in 
the TGT Memory Map, (5) . To find the 
location of the BL cells, add (5) 
(from the TGT table) to the entry 
point address of the object module, @. 

2. The first four bytes are the first BL 
cell, the second four bytes are the 
second BL cell, etc. Note that the 
third BL cell, (j) , contains the same 
value as that contained in register 6. 

Note: Ose of the FLOH and STATE 
options eliminates the need for the 
calculations described above. All 
that is needed for program debugging 
is the output from FLOH and STATE 
printed at the end of the listing, (§) , 
and described below. 

A. Specification of either FLOS or 
STATE causes the PROGRAM-ID, the 
completion code, and the PSW for 
the last problem program executed 
before the abnormal termination to 
be printed out. 

B. If STATE is in effect, the printed 
output includes the compiler- 
generated card number for the last 
verb executed. 

C. If FLOH is in effect, the words 
FLOH TRACE are printed out, 
together with the PROGRAM-ID and 
the card numbers of the procedure- 
names executed for all COBOL 
programs with the FLOH option in 
effect. 

For further discussion of the FLOH and 
STATE compiler options, including 
their relationship to the NOM option 
and to the SYMDMP option, see the 
chapter entitled "Symbolic Debugging 
Features." 
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JOOCl 
00002 
00CC3 
CCCC4 
00003 
0O0C6 
0O007 

oooca 

00CC9 
CO 010 
0O011 
C0C12 
00013 
00 014 
00C15 
00016 
0O017 
OO018 
0O019 
CO02O 
0O021 
00 022 
QCC23 
0OC24 
C0C25 
CCC26 
00027 
0OC28 
00C29 
OC030 
Q0C21 
0C032 
00033 
0CC34 
00 35 
00C36 
CCC37 
00038 
C0C39 
CCC40 
00041 
OO042 
00043 
00044 
00045 
O0C46 
O0C47 
00048 
0C049 
CCC50 
00051 
00052 
COC53 
00054 
00055 
00C56 
O0C57 
00056 
C0C59 
O0C6O 
00061 
00062 
00063 
00C64 
00065 
0OC66 
0C067 
00068 
CCC6S 
O0C70 
00C71 
00072 
00C73 
00C74 
00075 
00076 
0OC77 
00078 
CCC79 

cocao 

CCCEl 
CCC62 
OC083 
00C£4 
0OC£5 
00086 



100010 IDENTIFICATION uIVISION. 

10002J PROGRAM-ID. TEbTRUN. 

100030 AUTHOR. PROGRAMMER NAME. 

100040 INSTALLATION. PALO ALTO DEVELOPMENT CENTER. 

100050 OATE WRITTEN. AUGUST 8, 1976. 

100060 DATE-COMPILED. AUG 23,1976. 

10007k REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 

100080 COBOL USERS. IT CREATES AN OUTPUT FILE AND RE^DS IT 3AZK AS 

100090 INPUT. 

100100 ENVIRONMENT DIVISION. 

lOOllo CONFIGURATION ScCTIGN. 

100120 SOURCE-COMPUTcR. IBM-370-168. 

100130 OBJECT-COMPUTtR. IBM-370-168. 

1C014U INPUT-OUTPUT SECTION. 

10015O FILE-CONTROL. 

100160 SELECT FILE-1 ASSIGN TO UT-2400-S-S AMPLE. 

10017o SELECT FILE-2 ASSIGN TO UT-2400-S-SAMPLE. 

10018o DATA DIVISION. 

100190 FILE SECTION. 

10020O FO FILE-1 

100210 LABEL RECORuS ARE OMITTED 

10022J BLOCK CONTAINS 100 CHARACTERS 

10022a RECORD CONTAINS 20 CHARACTERS 

100230 RECORDING MuDE IS F 

10024^ DATA RECORD IS RECORD- 1. 

10025o 01 RECORD-1. 

100260 02 FIELD-A PICTURE IS X(20J. 

100270 FD FILE-2 

100280 LABEL RECORDS ARE OMITTED 

100290 BLOCK CONTAINS 5 RECORDS 

100300 RECORD CONTAINS 20 CHARACTERS 

10031o RECORDING MODE IS F 

100320 DATA RECORD IS RECORD-2. 

100330 01 RECORD-2. 

10034o 02 FIELD-A PICTURE IS X(20). 

1C035O WORKING-STORAGE SECTION. 

100360 77 KOUNT PICTURE S99 COMP SYNC. 

100370 77 NOMBER PICTURE S99 COMP SYNC. 

100375 01 FILLER. 

100380 02 ALPHABET PICTURE X«26) VALUE "ABC9EFGHI JKLMNOPQRST JVWXYZ". 

10039a 02 ALPHA REDEFINES ALPHABET PICTURE X OCCURS 26 TIMES. 

100403 02 DEPENDENTS PICTURE X(26> VALUE "3123401234012340123401234 

100410- "0". 

100420 02 DEPEND ReDEFINES DEPENDENTS PICTJRE X OCCJRS 26 THES. 

10044u 01 WORK-RECORJ. 

100450 02 NAME-FIElD PICTURE X. 

10046o 02 FILLER PICTURE X VALUE IS SPACE. 

100470 02 RECORD-Nu PICTURE 9999. 

100480 02 FILLER PICTURE X VALUE IS SPACE. 

10049u 02 LOCATION PICTURE AAA VALUE IS "NYC". 

100500 02 FILLER PICTURE X VALUE IS SPACE. 

100510 02 NO-OF-OEPENOENTS PICTURE XX. 

100520 02 FILLER PICTURE X(7) VALUE IS SPACES. 

100521 01 RECORDA. 

10052c 02 A PICTJRE S9(4) VALUE 1234. 

10052J 02 B RcoEFINES A PICTURE S9(7> COMPUT AT IONAL-3 . 

10053J PROCEDURE DIVISION. 

100540 BEGIN. 

100550 NOTE THAT Tht FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 

10056O AND INITIALIZES COUNTERS. 

1C057O STEP-1. OPEN OUIPUT FILE-1. MOVE ZERO TO KOUNT N01BER. 

100560 NOTE THAT TrtE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE 

1C0590 CONTAINED Iw THE FILE, WRITES THEM ON TAPE, AND DISPLAYS 

10060U THEM ON THE CONSOLE. 

100610 STEP-2. AOD 1 Tu KJUNT, ADD 1 TO NOMBER, «40VE ALPHA (KOUNT) TO 

1C0620 NAME-FIELD. 

100630 MOVE OEPEND (KUUNT) TO NO-OF-DEPENDENTS. 

100640 MOVE NOMBER TO RECORD-NO. 

10065u STEP-3. DISPLAY W3XK-REC0RD UPON CONSOLE. WRITE RECORD-1 FROM 

100660 WORK-RECORD. 

10C670 STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL T3 26. 

100680 NOTE THAT TriE FOLLOWING CLOSES OUTPUT AND REOPENS IT AS 

1C069O INPUT. 

10070O STEP-5. CLOSE FlLE-1. OPEN INPUT FILE-2. 

100710 NOTE THAT T.iE FOLLOWING REAOS BA;K THE FILE AND SINGLES OUT 

10C72O EMPLOYEES WITH NO DEPENDENTS. 

100730 STEP-6. READ FIlE-2 RECORD INTO WORK-RECORD AT END GO TO STEP-P. 

100731 COMPUTE 6 = B + 1. 

10C74U STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "Z» TO 

100750 NO-OF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO 

100760 STEP-6. 

100770 STEP-8. CLOSE FiLE-2. 

10078O STOP RUN. 
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INTRNL NAME 


LVL 


SOURCc NAME 


0NM=1- A 48 


FO 


FILE-i 


DNM=l-i68 


01 


RECORu-1 


DNM=l-i.89 


02 


FIELO-A 


DNM=i-<:U6 


FD 


FILE-*: 


DNM=l-226 


01 


RECORu-2 


DNM=l-«:47 


02 


FIELO-A 


DNM=W67 


77 


KOUNT 


DNM=l-«i82 


77 


NOMBErt 


DNM=I-i.98 


01 


FILLEit 


DNM=1-312 


02 


ALPHAoET 


DNM=l-.>30 


02 


ALPHA 


DNM=1-J48 


02 


DEPENDENTS 


DNM=1-j68 


02 


DEPENli 


DNM=1-J84 


01 


WORK-KECORO 


DNM=l-*08 


02 


NAME-HELD 


DNM=1~*26 


02 


FILLEK 


DNM=l-442 


02 


RECORu-'JJ 


0NM=1— tol 


02 


FILLEn 


DNM=1— *75 


02 


LOCATION 


DNM=l-493 


02 


FILLEK 


DNM=2-uO0 


02 


NO-OF-OEPENOENTS 


DNM=2-U26 


02 


FILLEK 


0NM=2-u40 


01 


RECORjA 


0NM=2-Jo0 


02 


A S~\ 


DNM=2-J71 


02 


B^<T) 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE 


DCB=01 




DNM=1-148 






OSAM 


BL = 1 


000 


0NM=1-168 


OS 


0CL20 


GROUP 


BL=1 


000 


DNM= 1-189 


OS 


20C 


DISP 


DCB=02 




DNM=l-2 06 






QSAM 


BL = 2 


000 


DN*(=l-226 


DS 


0:L20 


3PPUP 


BL=2 


000 


0NM=l-247 


OS 


23C 


DISP 


BL = 3 


000 


DNM=l-267 


OS 


1H 


COMP 


8L = 3 


002 


DNM=l-282 


OS 


1H 


COMP 


BL=3 


008 


DNM=l-298 


OS 


0CL52 


GRPJP 


BL=3 


008 


DNM= 1-312 


OS 


26: 


DISP 


BL=3 


008 


DNM=l-330 


DS 


1C 


DISP 


BL = 3 


022 


DNM=l-348 


OS 


25C 


DISP 


BL = 3 


022 


DNM=l-368 


DS 


i: 


DISP 


BL=3 


040 


DNM=l-384 


DS 


0CL2P 


GROUP 


BL = 3 


040 


DNM=l-408 


DS 


1C 


DISP 


BL=3 


041 


0NM= 1-428 


OS 


1C 


DISP 


BL = 3 


042 


0NM=l-442 


DS 


4C 


DISP-NM 


BL = 3 


046 


DNM= 1-461 


DS 


i: 


DISP 


BL=3 


047 


DNM=l-475 


DS 


3C 


DISP 


BL = 3 


04A 


DNM=l-493 


DS 


i: 


DISP 


BL=3 


04B 


DNM=2-000 


DS 


2C 


DISP 


8L = 3 


04D 


DNM=2-026 


DS 


7C 


DISP 


BL = 3 


058 


DN1=2-040 


OS 


o:L4 


3R0UP 


BL=3 


058 


ONM=2-360 


DS 


4C 


DISP-NM 


8L=3 


058 


DNM=2-071 


OS 


4P 


COMP-3 



MEMORY MAP 



TGT 



00318 



SAVE AREA 

SWITCH 

TALLY 

SORT SAVE 

ENTRY-SAVE 

SORT CORE SIZE 

RET CODE 

SORT RET 

WORKING CELLS 

SORT FILE SIZE 

SORT MOOE SIZE 

PGT-VN TBL 

TGT-VN TBL 

RESERVED 

LENGTH OF VN TBi. 

LABEL RET 

RESERVED 

DBG R14SAVE 

COBOL INDICATOR 

A(INITl) 

DEBUG TABLE PTR 

SUBCOM PTR 

SORT-MESSAGE 

SYSOUT DONAME 

RESERVED 

CQBJL ID 

COMPILED POINTED 

COUNT TABLE ADDkESS 

RESERVED 

DBG R11SAVE 

COUNT CHAIN ADOkESS 

PRBH CELL PTR 

RESERVED 

TA LENGTH 

RESERVED 

PCS LIT PTR 

DEBUGGING 

CD FOR INITIAL 1NPJT 

OVERFLOW CELLS 

BL CELLS 

DECBADR CELLS 

FIB CELLS 

TEMP STORAGE 

TEMP STORAGE- 2 

TEMP STORAGE-3 

TEMP STORAGE-4 

BLL CELLS 

VLC CELLS 

SBL CELLS 

INDEX CELLS 

SUBADR CELLS 

ONCTL CELLS 

PFMCTL CELLS 

PFMSAV CELLS 

VN CELLS 

SAVE AREA =2 

SAVE AREA =3 

XSASW CELLS 

XSA CELLS 

PARAM CELLS 

RPTSAV AREA 

CHECKPT CTR 

DEBUG TABLE 



00318 

00360 

00364 

00368 

0036C 

00370 

00374 

00376 

00378 

004A8 

004AC 

00480 

004B4 

004B8 

004BC 

004BE 

004BF 

004C0 

004C4 

004C8 

004CC 

004D0 

004D4 

004DC 

00400 

004DE 

004E0 

004 E4 

004E8 

004FO 

004F4 

004F8 

004FC 

00501 

00504 

0050C 

00510 

00514 

00518 

00518-*— (Y) 

00524 ^ 

00524 

00528 

00530 

00530 

00530 

00530 

00538 

00538 

00538 

00538 

00540 

00540 

00540 

00544 

0054C 

0054C 

00554 

00554 

00554 

00558 

00558 

00558 
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LITERAL POOL (HEX) 



O05BO (LIT + O) 
GCJCd (LIT+2f) 



C OOOOOOl 
000*4000 



JulAlCIO 

oyoajooo 



00 00001C 

cooooooo 



00000008 00000300 4B143030 



DISPLAY LITERALS (BCD) 
CC5D4 (LTL+3o) 'WORK-RECORD' 





DEBUG LINKAGE AkEA 


00560 




OVERFLOW CELLS 


0056C 




VIRTUAL CELLS 


00570 




PROCEDURE NAME uELLS 


0059C 




GENcRATED NAME CELLS 


0059C 




DCB ADDRESS CELlS 


005A0 




VNI CELLS 


005A8 




LITERALS 


005 BO 




DISPLAY LITERALj 


005D4 




PROCEDURE BLOCK CELLS 


005E0 


REGISTER 


ASjIGNMENT 




REG 6 
REG 7 


bL =3*-(?) 
BL =1 w 




REG 8 


BL = 2 





HORKIniG-STORAoE STARTS AT LOCAf ION OOOAO FOR A LENGTH QF 00060. 



el ♦ BEGI.'i 





0005E4 














0005E4 














0005E4 


5B 


SO 


C 


080 






0005E8 


58 


FO 


c 


024 






0005EC 


05 


IF 










0005EE 


00u0003D 




'STEP-1 


0005F2 














0005F2 


58 


FO 


c 


024 






0005F6 


05 


IF 










0005F8 


OOt/00040 




OPEN 


0005FC 
O006C0 


58 
05 


FO 
EF 


c 


028 






000602 


58 


10 


c 


040 






00060b 


58 


40 


1 


024 






00060A 


02 


02 


4 


Cll C 


02 D 




000610 


50 


10 





234 






000614 


92 


OF 


D 


234 






000618 


9o 


80 


D 


2 34 






0006 1C 


41 


10 


D 


234 






000620 


D2 


03 


D 


060 C 


057 




000626 


58 


FC 


c 


30 






00062A 


05 


EF 










00062C 


58 


10 


C 


040 






000630 


D2 


03 


D 


060 C 


05B 




00063b 


53 


FO 


c 


030 






0006 3A 


05 


EF 










00063C 


58 


70 


D 


200 




MOVE 


000640 


02 


01 


6 


000 C 


050 




000646 


D2 


01 


6 


002 C 


050 


'STEP-2 


00064C 














00064C 


58 


FO 


C 


024 






000650 


05 


IF 










000652 


00k/00u*4 




ADD 


000656 


48 


30 


C 


052 






0006 5A 


4A 


30 


6 


000 






00065E 


40 


30 


6 


000 




A 00 


000662 


48 


30 


C 


052 






000666 


4A 


30 


6 


002 






00066A 


40 


30 


6 


002 




MJVE 


00066E 


41 


40 


6 


008 






000o72 


48 


30 


6 


COO 






0006 7o 


5C 


20 


C 


050 






OC06 7A 


1A 


43 










0006 7C 


58 


40 


C 


50 






000680 


50 


40 


D 


220 






00068* 


58 


EO 


D 


220 






000688 


D<: 


00 


b 


040 E 


000 


MOVE 


00068E 


41 


40 


6 


022 






000692 


40 


30 


6 


000 






0006 9t> 


5C 


2U 


C 


050 






00069A 


1A 


43 










00069C 


58 


40 


C 


050 






0006AO 


50 


40 


D 


224 






0006A4 


58 


FU 


D 


224 





PN = 02 


EQU 


* 






START 


EQU 


* 








L 


11,080(0,12) 


PBL=1 






L 


15,024(0,12) 


V(ILPOFLWl) 






BALR 


1,15 








DC 


X'0000003D' 






PN=03 


EQU 


* 








L 


15,024(0,12) 


V(ILBOFLHl) 






BALR 


1,15 








DC 


X' 000000*0' 








L 


15,028(0,12) 


V(ILB0DPG4) 






BALR 


14,15 








L 


1,040(0,12) 


DCB = 1 






L 


4,024(0,1) 








MVC 


011(3, 4), 020(12) 




V( IL3CEXT0) 




ST 


1,234(0,13) 


SA3=1 






MVI 


234(13), X'OF' s 


SA3 = 1 






01 


234(13) ,X'BO' 


SA3 = 1 






LA 


1,234(0,13) 


SA3 = 1 






MVC 


063(4, 13), 357(12) 


WC=01 


LIT + 7 




L 


15,030(0,121 


V(ILBOaiOO) 






BALR 


14, 15 








L 


1,040(0,12) 


DCB=1 






MVC 


060(4, 13), 05BI12) 


WC = 01 


LIT+11 




L 


15,030(0,12) 


V(ILPD3I30) 






BALR 


14,15 








L 


7,200(0,13) 


BL =1 






MVC 


000(2,61,353(12) 


0NM=l-267 


LIT + O 




MVC 


002(2,61,050(12) 


DNM=l-282 


LIT + O 


PN=04 


EQU 


* 








L 


15,0241 0,12) 


VULP0FLH1) 






BALR 


1,15 








OC 


X'00000044' 








LH 


3,052(0,12) 


L1T + 2 






AH 


3,000(0,6) 


DNM=l-267 






STH 


3,000(0,6) 


DNM = l-267 






LH 


3,352(0,12) 


LIT + 2 






AH 


3,002(0,61 


DNM=1-2P2 






STH 


3,002(0,61 


DNM=l-282 






LA 


4,038(0,6) 


DN1=l-3?0 






LH 


3,000(0,6) 


DNM=l-2b7 






* 


2,050(0,12) 


LIT + O 






AR 


4,3 








S 


4,050(0,12) 


LIT + O 






ST 


4,220(0,13) 


SBS=1 






L 


14,220(0,13) 


SBS = 1 






MVC 


040( 1,6), 000(14) 


DNM=l-408 


DMM=l-3?0 




LA 


4,022(0,6) 


DNM=l-368 






LH 


3,000(0,6) 


DNM=l-267 






M 


2,050(0,12) 


LIT + O 






AR 


4,3 








S 


4,050(0,12) 


LIT + O 






ST 


4,224(0,13) 


SBS = 2 






L 


15,224(0,13) 


SBS=2 
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J08 TtSTRUN STEP GO 

CCKPLETION COOfc SYSTEM = JC7 

PSW AT ENTRY TO ABEND 078D200u 00075F46 



TIME 202835 DATE 76236 



ASCB OOFCDCAO 



ASC8 

10SP 

LOA 

cWST 

OUMP 

VSC 

oUCB 

rtLC 

smct 



7CDB60 K8P 
MSS 
FSA 
LTC 
iTAB 
KfcSV 
tXT2 



C1E2C3C2 

00000000 
007FF548 
897CAF22 
OC7FF003 
00000058 
00FCDC40 
00000000 
00000000 



007F0900 
007D1690 
01074FB0 
OOOOOOOO 
007FD04C 
OOOOOOOO 
OO7C0C88 
fMSAV OOOOOOOO 
610 E3C3C240 
KPT OOOOOOOO 
cVENT OOOOOOOO 



FWOP 

SPL 

RSM 

XWST 

FWi 

TCBS 

OJXB 

JBNI 

SWTL 

PIE 

PK-FLG 

ICB 

1QE 

TCT 

iOBKC 

«EC8 

AfaCR 

KTM1 

UBTB 

kESV 



O0FE83F8 
OOFCDD70 
OOFCOB60 
4016BOOO 
FFFFOOOO 
000000O1 
00FF2CC8 
00FE8B98 
00001410 

OOOOOOOO 
80010000 
OOOOOOOO 
OOOOOOOO 
807FC010 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 



BW3P 
CPUS 
CSCB 
JSTL 
THCH 
LOCK 
FMCT 
JBNS 
SRBT 

DEB 

FLG 

TME 

ECB 

USER 

XCPD 

RESV 

RESV 

ESTA 

SWAS 

RESV 



00FBCA28 
00000001 
00FCDD88 
0000011E 
OOOOOOOO 
OOOOOOOO 
00290000 
00FCDD98 
OOOOOOOO 

007D3B80 
OOOOFFFF 
OOOOOOOO 
0070EFB4 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
80000000 
007D0F30 
OOOOOOOO 



CMSF 

IDSQ 

TSB 

ECB 

ASXB 

LSOH 

XMPO 

LGCB 

ATME 



00003000 
00200006 
OOOOOOOO 
807F0790 
007FF300 
00003300 
OOOOOOOO 
OOOOOOOO 
33E76000 



TIO 007D5020 
LLS 007DEA€0 
JST 007CDB60 
TSF 20000000 
SOF OOOOOOOO 
EXT OOOOOOOO 
BAK 0O7FCA0O 
FOE OOOOOOOO 
'JKY 007D17A0 
SCB 00000003 
RES OOOOOOOO 



SVRB 
IODP 
EJST 
UBET 
SWCT 
QECB 
IQEA 
VGTT 



33333333 
U4E0079 
00000301 
897C998A 
7AOCOOO0 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 



CMP 

JLB 

NTC 

D-POE 

MOID 

BITS 

RTMWA 

SWA 

CPVI 

GTF 

RESV 



900C7000 
037D1F00 
OOOOOOOO 
007FF548 
00000333 
OOOOOOOO 
037CD700 
00701820 
0040FFFF 
00000300 
OOOOOOOO 



SYNC 
STOP 
XJST 
QSCV 
SSRB 
1ECe 
RTWA 

p:tt 



33003300 
3F35EC00 
FFOF2000 
331FF630 
OOOOOOOO 
43003300 
03003300 
OOOOOOOO 



TRN 

JPO 

OTC 

AQE 

JSCB 

DAR 

IOTM 

RESV 

BYT1 

SVAB 

RESV 



OOOOOOOO 
007AC090 
007FCA03 

oo7:o:f8 

307D0F64 
OOOOOOOO 
OOOOOOOO 
00000003 
48040000 
30300003 
OOOOOOOO 



ACTIVE RBS 



7CF040 RESV 

FLG1 



OOOOOOOO RtSV OOOOOOOO RTPSW1 078D2000 

02000000 Wl-L-IC 00060007 
KESV OOOOOOOO APSW OOOOOOOO SZ-STAB 00110082 

v/TTR OOOOOOOO WT-LNK 007C0B60 

KG 0-7 007CF010 00074FF8 00000040 007F26F4 

KG d-15 007DEF90 807FC010 OOOOOOOO 007FCC08 



00075F46 RTPSW2 00060007 000760FF 

FU-COE 007D1ED8 PSV 373D2333 03375F46 



037F26D0 
70DCA602 



007FCA00 
00074FP0 



00705018 
*3DCA8FC 



FDOOOOOO 
OO7DEFC0 



SVRB 7FD900 itESV OOOOOOOO KESV OOOOOOOO RTPSW1 OOOOOOOO 



OOOOOOOO RTPSW2 OOOOOOOO 



FLG1 20000000 
KESV OOOOOOOO 
J/TTR OOOOOOOO 



KG 0-7 
KG 8-15 
tXTSA 



40075F3C 
0007AA70 
40075F3C 
00 7C 07 DO 
OOOOOOOO 



*C-L-IC 00020033 
APSW OOOOOOOO 

*T-LNK 007CF040 
0007AA70 
00076082 
0007AA70 
FF000368 
OOOOOOOO 



SZ-STAB 0019D022 



FL-CDE OOOOOOOO PSW 070C1000 



40075F3C 
000756B8 
00018C30 
40000101 
OOOOOOOO 



0000001A 
00075C9C 
007CDB60 
900C7000 
OOOOOOOO 



000758C8 
00075C18 
037FD9DO 



00075688 
00075900 
OOFCDCAO 



33075758 
50075F24 
0003AA64 



SVRB 7F0900 KESV OOOOOOOO KESV OOOOOOOO RTPSW1 OOOOOOOO 



FLG1 020C0000 
KtSV OOOOOOOO 
w/TTR OOOOOOOO 



KG 0-7 
kG 8-15 
cXTSA 



OOOOOOEO 
007DDE68 
00000300 
OOOOOOOO 
OOOOOOOO 



wC-L-IC 0002000C 
APSW OOOOOOOO 
*T-LNK 007FD9D0 
007CD8DO 
OOOOOOOO 
007CD418 
OOOOOOOO 
OOOOOOOO 



SZ-STAB 00190022 



RTPSW2 00030000 



FL-CDE OOOOOOOO PSW 373C2333 



O0FE404O 
007D0F50 
000003B4 
OOOOOOOO 
OOOOOOOO 



0080E600 
007DOEC0 
007FD964 
OOOOOOOO 
OOOOOOOO 



007CDB60 
037CD7F0 
2OF0O000 



007C3800 
007CD944 
OOOOOOOO 



50D4801C 
50D4828: 
03003303 



0007M1C 
6001FC3C 
OOOOOOOO 



007CP7DO 
OOOOOOOO 
00000300 



NE 007DEOBO 
NE 0O7AC050 
NE 007DE0E0 
NE 00/DEB48 
NE OOuOOOOO 



RSP-CDE O0FE83D0 
RSP-CDE wOFECFOO 
RSP-CDE O0FBD2A0 
RSP-CDE U070E140 
RSP-CDE 007D1928 



CNT 00010001 
CNT 00010001 
CNT 00010001 
CNT 00010000 
CNT OOOIOOOO 



NE 007AC080 RSP-CDE 30FE8EBO CNT 00010001 

NE 007DEOOO RSP-CDE 007AC070 CNT 30310033 

NE 0070E120 RSP-CDE OOFCD700 CNT 00010001 

NE 007D1918 RSP-CDE 307DEB58 CNT 00010033 



701 ED8 


NCDE 


OOOOOOOu 


RBP 


007CF040 


NM 


GO 


EPA 


000756B8 


XL/MJ 


007CF0O0 


FE80DO 


NCDE 


00FE9F3o 


RBP 


OOOOOOOO 


NM 


IGG019DK 


EPA 


OOF2AOO0 


XL/MJ 


O0FE8DFO 


FE8EB0 


NCDE 


00FED8«:u 


RBP 


OOOOOOOO 


NM 


IGG019AA 


EPA 


00F1EF60 


XL/MJ 


OOFEBEDO 


FECFDO 


NCDE 


00FEE78J 


RBP 


OOOOOOOO 


NM 


ISG019AQ 


EPA 


OOBE1018 


XL/MJ 


OOFECFFO 


7AC070 


NCDE 


007DEB2t> 


RBP 


007F09D0 


NM 


ILBOD220 


EPA 


0007C6FA 


XL/MJ 


007AC090 


7AC090 


NCDE 


007AC07U 


RBP 


OOOOOOOO 


NM 


ILB0322 


EPA 


0007C6F8 


XL/MJ 


007AC060 


FBD2A0 


NCOE 


00FC070u 


RBP 


OOOOOOOO 


NM 


IGG019CW 


EPA 


OOBD6A40 


XL/MJ 


00FBD2C0 


FCD700 


NCDE 


OOFCElflu 


RBP 


OOOOOOOO 


NM 


IGG019CU 


EPA 


00D61898 


XL/MJ 


03FCD720 


7DE140 


NCDE 


007DEACO 


RBP 


007FD9D0 


NM 


ILB00210 


EPA 


00079674 


XL/MJ 


007DE828 


7DEB28 


NCDE 


007DE14u 


RBP 


OOOOOOOO 


NM 


ILB0D21 


EPA 


00079678 


XL/MJ 


0070E13O 


7DEB58 


NCDE 


007CB01U 


RBP 


007FD900 


NM 


ILB0D200 


EPA 


00079C42 


XL/MJ 


0070EACO 


7DEAC0 


NCOE 


0070EB5o 


RBP 


OOOOOOOO 


NM 


ILBOD20 


EPA 


00079C40 


XL/MJ 


007CB678 


7D1928 


NCDE 


007DlEDu 


RBP 


007FD9D0 


NM 


ILB00010 


EPA 


000753B4 


XL/MJ 


007CBOIO 


7CB010 


NCDE 


007D1928 


RBP 


OOOOOOOO 


NM 


ILBOD01 


EPA 


000753A8 


XL/MJ 


007CB00O 



USE 33313333 
USE OOOIOOOO 
JSE 00020000 
USE 00030000 
USE OOOOOOOO 
USE 33313033 
USE 00020000 
USE 00020000 
USE 33303030 
USE OOOIOOOO 
USE OOOOOOOO 
USE OOOIOOOO 
USE OOOOOOOO 
USE 33313033 



ATT* 
ATTR 
ATT* 
ATTR 
ATTR 
ATT* 
ATTR 
ATTP 
ATTP 
ATTR 
ATT* 
ATTR 
ATTR 
ATTR 



0820000 
BO2200O 
B022000 
8922000 
3710000 
3320000 
e023000 
B122000 
3710000 
3320000 
3710000 
3320000 
3710000 
3320000 



Figure 100- Prograa with Data Interrupt (Part 4 of 5) 



272 



INTERRUPT AT 075F46 



PROCEEDING BACK VIA REG 13 

SA 0759D0 «D1 0030C4C2 HSA OD074FBO LSA 00074B90 RET 50075F24 

fcl 0007AA70 R2 00075900 R3 OOOOOOl'A R4 000758C8 

k7 0007AA1C R3 0007AA70 R9 00076082 RIO 000756B8 



EPA 6001FC3C RO 40075F2C 
R5 000756B8 R6 00075758 
Rll 00076176 R12 00375C18 



GO WAS cNTERED VIA LINK 

SA O74FB0 KOI OOOOOOOO HSA 00000000 LSA 00075900 RET 00018C80 EPA 0D0756B8 RO 007CF010 

Rl 00074FF8 R2 00000040 R3 007F26F4 R4 007F26D0 R5 007FCAOO R6 00705018 

R7 FDOOOOOO R8 0070EF90 R9 807FC010 RIO OOOOOOOO Rll O07FCC08 R 12 70DCA602 

VTAM NOT ACTIVE FOR THIS CALL 

REGS AT ENTRY TO ABEND © 



OOOOOOOOOOOoOOOO 



0000000000000000 



O0OOOOOOO0O0D3OD 



0000000000000000 



REGS 0-7 
REGS 8-la 



40075F3C 
0007AA70 



U007AA70 
O0076082 



40075F3C 
000756B8 



0000001A 
00075C9C 



000758C8 
00075C18 



00075 6B 8 
03375900 



0007575 8 
50075F24 



0007 AA1C 
6001FC3C 



LOAC MODULE 



C756A0 
C156C0 
C156E0 
U57CC 

L 
CI 5740 
075760 
075780 
0757A0 
0757CO 
C757E0 
C7580O 
07 5820 
C75640 
075860 



4580F010 
0001o7FE 
CCOOoOOO 
[NE 07*720 
F2F04BF1 
C1C2C3C4 
F1F2F3F4 
E8C3*0F0 
OOOOOOOO 
OOOOoOOO 
00000006 
03C5*040 
OOOOUOOl 
OOOO'JOOO 



E3C5E2E3 D9E*D540 
00076082 000756b8 
OOOOOOOO OOOOOOOO 
SAME AS ABOVc 
F84BF5F4 C1E»C740 
C5C6C7C8 C9D1D203 
F0F1F2F3 F4FoFlF2 
40404040 404O4040 
OOOOOOOO OOOOOOOO 
OOOOOOOO OOOoOOOO 
00830000 0007AA01 
02000048 OOOoOOOl 
00000014 OOOoOOOl 
OOOOOOOO OOOOOOOO 



E5E2D9F1 O700989F F02407FF 

000756B8 00075C18 000759DO 

OOOOOOOO OOOOOOOO OOOOOOOO 



F2F36B40 

0405D607 

F3F4F0F1 ^^ 

OOOOOOOO (4) 

0507795A 

OOOOOOOO 

00004000 

08000001 

OOOOOOOO 

00900000 



F1F9F7F6 
0809E2E3 
F2F3F4F0 
|F1F2F3C4| 
000756DE 
80000000 
00000001 
00000064 
00000001 
OOOOOOOO 



OOOOOOOO 
E4E5E6E7 
OOOOOOOO 
OOOOOOOO 
00000001 
OOOOOOOO 
46000001 
OOOOOOOO 
05EF3703 
02000001 



90ECO00C 185005F0 
96021034 07FE41F0 
00075C9C 00076042 
OOOOOOOO OOOOOOOO 

001A001A OOOOOOOO 
E8E9F0F1 F2F3F4F0 
C140FOFO F0F140D5 

00000000 OOOOOOOO 

00000001 OOOOOOOO 

00000000 OOOOOOOO 
00D757BC E2CID4D7 

00000001 00000001 
OOOOOOOO OOOOOOOO 
00140014 OOOOOOOO 



*..O.TESTRUN VSR1....0 0* 



*20.18.54AUG 23. 1976 * 

♦ABCDEFGHIJKLMNDPQRSTUVWXYZ 012340* 
*12340123401234012340....A 0001 N* 
*YC ....123D * 



* SMP* 

*LE * 



©j 
© 

© 



075880 

L 
0758CO 
C758E0 
0159C0 
075920 
075940 
C7596C 
C75980 
C759A0 
7 59CO 
C759EO 
075AC0 
075A20 
C15A40 
G75A60 
C15A80 
C15AA0 
07SACO 
075AE0 
C75800 
C75620 
C7 5B40 
C75860 
C15B80 
075BAO 
075BCO 
C75BE0 
C75COO 
C75C20 
075C40 
C75C60 
C7 5C80 

PRCGPAM 



OOOOJOOO 
[NE 0738A0 
OOOOuOOO 
OOOOUOOl 
COOOOOOO 
46077F8C 
2020<:020 
C5EFO7O0 
0204o00i 
OOOOoOOO 
OOOOoOOO 
6001t-C3C 
0007AA1C 
OOOOjOOO 
0007a900 
0007o082 
0007»7F4 
5820O1A8 
OOOOoOOO 
60073D48 
00073960 
OOOOoOOO 
OOOOoOOO 
OOOOuOOO 
00073668 
OOOOoOOO 
OOOOOOOO 
OOOOOOOO 
OOOOoOOO 
C7FBJ000 
00070172 
00073DF6 
0004*000 



OOOOOOOO OOOOOOOO 
SAME AS ABOVt 

00000000 OOOOOOOO 

00000001 OOOoOOOO 
OOOOOOOO OOOOOOOO 
900758C8 00Co4800 
0007A920 0007AAD4 
OOOOOOOO OOOoOOOO 
00140804 OOOOOOOO 
OOOOOOOO OOOOOOOO 
OOOOOOOO OOOuOOOO 
40075F3C 0007AA70 
0007AA70 00076082 
00075C9C OOOOOOOO 
00075900 OOOoOOlA 
000756B8 00O75C9C 
0000001A OSFuFOOO 
07F20000 000009C8 
OOOOOOOO OOOOOOOO 
000750A0 OOOoOOOO 
80C75900 00075900 
00076082 000756B8 
OOOOOOOO OOOOOOOO 
OOOOOOOO OOOoOOOO 
00000558 00078D98 

00000000 00075:9c 

OOOOOOOO OOOoOOOO 
0JOO0O1C OOOoOOOO 
80075900 OOOOOOOO 
00076C18 000/845A 
0007795A 00077Et2 
OOOOOOOO OOOuOOOl 
OOOOOOOO COOoOOOO 



OOOOOOOO 

OOOOOOOO 
OOOOOOOO 
00000005 
00703414 
0007AA70 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
00075900 
000756B8 
OOOOOOOO 
000758C8 
00075C18 
OOOOOOOO 
00074EDO 
00075D9E 
0000001A 
0000001A 
00075C9C 
OOOOOOOO 
OOOOOOOO 
E2E8E206 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
00076162 
00076F6A 
001A1C10 
E606D9D2 



OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 



(I) 



OOOOOOOO 
OOOOOOOO 
0083C300 
12F1EF60 
00000014 
OOOOOOOO 
0007BF40 
OOOOOOOO 
0030C4C2 
OOOOOOIA 
00076176 
04400000 
000756B8 
50O77EFO 
OOOOOOOO 
20000000 
OOOOOOOO 
00075793 
000758C8 
00075C18 
OOOOOOOO 
OOOOOOOO 
E4E34040 
00075C98 



OOOOOOOO 
OOOOOOOO 
0507AAOO 
00BE1018 
00000001 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
00074FB0 
000758C8 
00375C18 
50075F24 
00075758 
46075F36 
58B001D8 
OOOOOOOO 
01000000 
50076 0E6 
000756B8 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
E380000C 
OOOOOOOO. 



0507795A 
OOOOOOOO 
00004000 
07000001 
OOOOOOOO 
00900000 
OOOOOOOO 
OOOOOOOO 
O0074B9O 
000756B8 
3D02804B 
12F1EF60 
0007AA1C 
0007AC10 
F870D210 
OOOOOOOO 
00075D8C 
00018C80 
00075758 
OOOOOOOO 
OOOOOOOO 
40075F3C 
00075740 
OOOOOOOO 



0O0756B8 
00075779 
OA00098A 
000779AA 
0O07845E 
0000001C 
6009C5C3 



0007AA70 l00Q75758l 
OO075DF6 
50B0D1D8 
0007845A 
000 757F4 
OOOOOOOO 
03075C9C 



00075793 
16340000 
00076176 
00075F36 
00000008 
06D9C400 



000756DE 
80000000 
0007A8B8 
000D0064 
00B06A40 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
50075F24 
00075758 
OOOOOOOO 
0007AC10 
0007BFE8 
80075900 
C0560700 
OOOOOOOO 
00076F6A 
O0O7795A 
0007AA1C 
OOOOOOOO 
OOOOOOOO 
6007839C 
OOOOOOOO 
00030000 
OOOOOOOO 
000750F6 
58B0C01C 
000779AE 
00075900 
48140000 
5 8B0C080 



LAST PSW BEFOKE ABEND = FF8500o7E0075F46 



COBOL ABEND DIAGNOSTIC AJDS 



SYSTEM COMPLETION CODE = 0C7 



LAST CARD NUMoER/VERB NUMBER EXECUTED — CARD NUMBER 000081/VERB NUMBER 01. 

FLOW TRACE 
TESTRUN OOOO08 000072 000068 000072 000068 000072 000068 000072 000077 000080 



.00 JQ8.K. 



* SYSOUT 



.VOPK. RECORD * 



Figure 100. Program with Data Interrupt (Part 5 of 5) 
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24 
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Buffer 
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control 
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variable 
data record 
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displacement 
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L . : J 



Figure 101. Locating the QSAM Logical Record Area 



Loca tin g Data Areas for spanned Records 



2SAH* QSAM (sequential) spanned records 
allocate a Logical Record Area in which 
complete logical records may be assembled 
(see "Record Formats") . Figure 101 
illustrates the relationship between the 
DCB, the Buffer Areas, and the Logical 
Record Area. 



1. The DCB contains the DCBBUFCB field at 
a displacement of 2 1 bytes from the 
origin of the DCB. The contents of 
DCBBUFCB points to the origin of the 
Buffer Control Block (BUFCB) in the 
Buffer Area. 

2. The BUFCB field contains an 
Area-Address (A (Area) ) at a 
displacement of 8 bytes from the 
origin of the Buffer Area. The 



Area-Address points to the origin of 
the Logical Record Area. 

3. The Logical Record Area contains a 
displacement field at a displacement 
of 5 bytes from its origin. This 
field contains a value from to 8 
indicating the number of bytes the 
record has been displaced. The 
contents of this 1-7 byte field must 
be added to the value 24 (the first 
byte in the variable data record 
origin area) in order to locate the 
beginning of the logical data record 
within the Logical Record Area. Note 
that the first 4 bytes of the Logical 
Record Area are control data 
indicating the length of the Logical 
Record Area (including the 4 bytes of 
control data) . 

Note: The Logical Record Area is not 
allocated for QSAH records formatted in V, 
U # or F mode. 
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variable 4 
< bytes ><-bytes-><- 

r t t — t — 

J REC-ID ] LL j 11 | 
L X X X 



variable 
— bytes 



> 



Maximum 01 



Logical Record Area 



18 variable 4 variable 
< bytes > < — bytes — ><-bytes->< bytes > 







T T 






BUFCB 


| REC-ID 


1 LL J 


111 


Data Segment 




X 


X X 


X 





Buffer 
Control Block 



Segment Work Area 



L J 

Figure 102. Logical Record Area and Segment Work Area for BDAH and BSAM spanned Records 



BSAM, and, BfiAM: BSAM and BDAM (direct) 
spanned records allocate a Segment Work 
Area. This work area is used for temporary 
storage of record segments before a 
complete logical record is assembled in the 
Logical Record Area. Figure 102 
illustrates the Logical Record Area and the 
Segment Work Area. 



No te: The segment work area is not 
allocated for BSAM and BDAM records 
formatted in V, U, or F mode. 



The following discussion illustrates the 
relationship between the DCB, the Logical 
Record Area, and the Segment Work Area as 
shown in Figure 102. 



The DECB address plus 12 bytes points 
to the beginning of the Logical Record 
Area. 



Sfiil 



1. 



2. 



The DCB address plus 100 bytes points 
to the beginning of the BUFCB (Buffer 
Control Block) . 

The contents of the BL assigned to the 
level-01 entry in an FD points to the 
Logical Record Area labeled "Maximum 
01" in Figure 102 (see Figure 98 for 
an example of the BL pointer.) 



BS AM ou tput 

1. The DCB address plus 76 bytes points 
to the beginning of the BUFCB (Buffer 
Control Block) . 



gSAM input 



1. The DECB address plus 12 bytes points 
to the beginning of the Segment Work 
Area. 



The DCB address plus 100 bytes points 
to the beginning of the Logical Record 
Area. 



4oc§ting_fCAg i ^ata, Areas 



In a teleprocessing application, control 
blocks, called gueue blocks, are created 
for a given partition/region. For input 
operations, the number of queue blocks 
created agrees with the number of queues 
accessed. For output operations, however, 
only one queue block is created for each 
partition/region. The numerals within the 
boxes in Figures 103 and 104 refer to the 
numbered paragraphs below. 

1. The TGT address plus 440 bytes points 
to the SUBCOM field (see Figure 184 in 
Appendix J: "Fields of the Global 
Table") . The fullword at x*50' bytes 
into SUBCOM points to the first 
RECEIVE queue block. The fullword at 
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2. 



X«54» off SUBCOM points to the SEND 
queue block. In both erases, the first 
field contains the data control block 
(DCB) . 



At X*58» bytes into either a RECEIVE 
or a SEND queue block, the first byte 
of the 4-byte field indicates whether 
the address that follows represents a 
TCAH buffer or a BSAM buffer. If the 
two high-order bits are on, the 
address contained in the next three 
bytes is for a TCAM buffer. 



Note: For TCAM there is only one 
buffer; for BSAM there is one buffer 
for each queue. 



Relative 
Location 



Field 






r— ■ 


. _ _ __, 

RQBDCB 1 | 


58 




8QBUFAD 2 i 


5C 


i 


RQBUFSIZ 3 | 


5E 


l~ 


RQBSUMGV 4 J 


60 




RQBDECB 5 J 


74 




RQBNEXT 6 J 


78 


i 


RQBAMTL 7 J 


7A 


1 


RQBDTS 9 J 


90 


r 


RQBDDNAM 11 | 


98 


i .. 


RQBRECDL 12 J 


99 


r 


RQBHELDC 13 J 


9A 




8QBISITP 14 | 


9B 


i 


Reserved ) 


9C 


r 


RQBNBL 15 J 


A0 


i — 


EQBQNAME 16 I 
— ._j 



Relative 
Location 




Field 







r 


IHADCB 1 


i 

I 
l 


58 


i 


SQBUFAD 2 


1 

1 
■ 


5C 


r — 

1 1 ,, 


SQBUFSIZ 3 


f 

I 
■ 


5E 


1 
i 


SQMORER 8 


1 

! 
• 


60 


r 


SQBENDIC 10 


■f 

1 
i 


61 


t ., 


SQBRECDL 12 


i 


62 


1 

L 


Reserved 




64 


r 


SQBDNLH 17 




68 


1 .... 


SQBMPLFH 18 




6C 


r 


SQBPBFH 19 




70 


L. 


SQBFSTOA 20 


i 


74 


1 

1 

\ .... 


SQBFSTOL 21 


f 

I 
i 


Figure 104. 


Field 


s of the SEND 


Q« 



Figure 103. Fields of the RECEIVE Queue 
Block 



3. In either a RECEIVE or a SEND queue 
block, this field specifies the size 
of the buffer, whose format is 
pictured in Figure 10 5. (For a list 
of codes used in the TCAH control 
byte, see Figure 106.) 

4. The RQBS0MGV field of the RECEIVE 
queue block indicates the number of 
bytes of data given to the user for 
this request. 

5. The RQBDECB field of the RECEIVE queue 
block contains the data event control 
block (DECB) . 

6. In the RECEIVE queue block, the 
RQBNEXT field provides the address of 
the next queue block. If this field 
is zero, there are no additional queue 
blocks. 

7. The RQBAMTL field of the RECEIVE queue 
block indicates the amount of data 
being held froa the last request. 

8. For BSAH only, the SQHORER field of 
the SEND queue block indicates the 
number of unused bytes left in the 
buffer. 

9. The 22-byte RQBDTS field of the 
RECEIVE queue block contains the date 
and time of the last message received 
from this queue, as well as the source 
of the message. 

10. The SQBENDIC field of the SEND queue 
block contains the end indicator {in 
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zoned decimal) specified in the COBOL 
source statement. 



INCOMPLETE ABNORHAL TERMINATION 



11. The BQBDDNAM field contains the ddname 
for the queue block specified in the 
COBOL teleprocessing program. 



If a job is abnormally terminated and 
the abnormal termination process goes to 
completion, the following procedures are 
carried out: 



12. The RQBRECDL field in the RECEIVE 

gueue block and the SQBRECDL field in 
the SEND queue block contain the 
record delimiter specified in the MCP. 



13. The RQBHELDC field in the RECEIVE 

gueue contains a character that, in 
some instances, is the next data 
character. 



A dump (ABDUMP) is produced by the 
system. 



The data sets in the job steps are 
disposed of as specified in the DISP 
parameter (i.e., kept, deleted, etc.). 
This is indicated in the job scheduler 
disposition messages produced for the 
job step. 



14. The RQBISITP field in the RECEIVE 
queue block is a switch byte. 



Temporary data sets, including those 
passed from previous job steps, are 
deleted. 



15. The RQBNBL field contains the 
enable/disable link. 



16. The RQBQNAME field contains the TCAM 
gueue name. 

17. The SQBDNLH field contains the head of 
the DNL (destination name list) . 

18. The SQBMPLFH field contains the free 
list head of the MPL (message phrase 
list) . 

19. The SQBPBFH field contains the free 
list head of the PB (phase buffer). 

20. The SQBFSTOA field contains the free 
storage pointer. 

21. The SQBFSTOL field contains the free 
storage length. 



15 6 14 

V TCAM Source ID Data 
prefix control 
Byte 

Note : The prefix, the TCAM control byte, 
and the source ID must be user specified 
for a SAM file* However, if the user 
invokes the SEND statement to create a 
SAM -file for subsequent input, then the 
COBOL compiler adds bytes 1 through 13 
(see Figure 148 in the chapter entitled 
"Using the Teleprocessing Feature"). 

Figure 105. Structure of a TCAM Record 



When the abnormal termination process 
does not go to completion {i.e., no end of 
dump message is present), none of these 
procedures will be carried out. Those 
data sets in the job step that were in 
existence previous to the point at which 
the error condition occurred will remain 
in effect. For data sets on direct access 
volumes, the names will remain tabulated 
in the Volume Table of Contents (VTOC) of 
the volume (see "Additional File 
Processing Information" for details on the 
VTOC). The result of an incomplete 
abnormal termination is that space needed 
by a subsequent job will be unavailable, 
or, if the same job is then rerun, 
duplicate name definition will result for 
those data sets that are newly created in 
the job step. This is true for temporary 
data sets for which the system has 
assigned the name, as well as data sets 
for which the programmer has assigned the 
name. 
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I Code | Meaning 



h 



+ 



| X'FlMThe first block of a multiblock 

I 1 message 

i I 

J X*F5'Jfh e first block of a multiblock 

J | message, with end of segment 

I J indicated 



»~ 



+ 



J X'UO'J&n intermediate data block 

I 1 

J X'FI'JAn intermediate data block, with 
| | end of segment indicated 



+ 



| X l F2«|The last block of a multiblock 

\ } message 

I ) 

J X*F6 , JThe last block of a multiblock 

J J message, with end of segment 

I J indicated 
4 



1 X*F3*JA single block message 

1 I 

\ X'F7'JA single block message, with end 

J J of segment indicated 

Figure 106. Codes Used in the TCAM Control 
Byte 



SCRATCHING NON-VSAM DATA SETS 



To avoid duplicate name definition and 
to ensure that space will be available for 
newly created data sets, the programmer can 
scratch his direct-access volume data sets 
by using the utility program IEHPROGM. To 
scratch such a data set means to remove its 
data set label (which includes its name) 
from the VTOC and to make the space 
assigned to it available for reallocation- 
Scratching does not uncatalog any cataloged 
data sets. This is done by the UNCATLG 
option of the IEHPROGM. 

If a DSNAME parameter has been specified 
in the DD statement for the data set, the 
IEHPROGM utility program requires the name 
of the data set. For data sets named by 
the programmer, the specified name is the 
dsname. For data sets for which the 
DSNAME=&Sname convention has been used, an 
internal name 

SYSyyddd.Ttttttt.axnnn. jobname. name 

is assigned by the system, where jobname is 
the name of the job and name is from the 
S&name. If no DSNAME parameter is 
specified, an internal name is assigned by 
the system. For data sets with no DSNAME 
parameter there exists an option by which 
the programmer can specify that all such 
data sets on the volume be scratched, 
without having to specify their names. 



If the programmer wishes to obtain a 
listing of the names of all the data sets 
on a yolume, including system-assigned 
internal names, he can use the utility 
program IEHLIST. This program provides a 
listing of the VTOC of the volume. 



Information on how to use these utility 
programs is contained in the publication 

OS/VS Utilities. 



OBTAINING EXECUTION STATISTICS 



Execution statistics are invoked via the 
COUNT option at compile time and the 
presence of SYSDBOUT and SYSCOUNT DD 
statements at execution time. No source 
language coding changes are required. 
COUNT facilitates testing, debugging, and 
optimizing by providing the programier with 
verb counts at the following times: 

• STOP RUN 

• GOBACK in the main program 

• Abnormal termination of a job. 

• At CANCEL time, verb counts for the 
canceled program and any of its 
subprograms. 

When COUNT is specified, the following 
iteias should be taken into account: 

1. When COUNT is specified, the compiler 
divides the program into blocks of 
verbs. When the statistics are 
printed, the last block of verbs 
executed in each program unit is 
indicated. If the program abnormally 
terminates, the statement causing the 
abnormal termination can be determined 
(by using the symbolic debugging 
features, for example) . The 
programmer should then subtract one 
from the verb count for each verb 
flagged which follows the abending 
verb. 

2. If COUNT is requested, the user may 
need to increase the REGION parameter 
on his load module EXEC card. The 
dynamic space required for COUNT is 
approximately 512 bytes plus 80 bytes 
per program unit being monitored, and 
four bytes per count block (see the 
compiler output statistics) . The 
requirements for each program unit are 
rounded to the next 128-byte boundary. 

3. The OTHERWISE verb is treated as if 
the user coded the ELSE verb. 

4. Both the SYSDBOUT and SYSCOUNT DD 
statements must be specified at 
execution time, 
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Debu gging and Testing 

The execution statistics clearly 
identify the following areas of the 
program: 

• untested and weakly tested areas of the 
program 

• The last blocks entered and executed 

• Possible sources of unnecessary code 

• The most heavily used parts of the 
program; that is, those parts most 
susceptible to changes. 



OPTIMIZATION METHODS 

Based on execution frequency, the 
following types of optimization can be 
implemented by the user: 

• Resequencing the prograi 

• Insight into SYMDMP 

• Common expression elimination 

• Backward movement 

• Unrolling 

• Jamming 

• Unswitching 

• Incorporating procedures inline 

• Tabling 

• Efficiency guidelines 

Note, however, that each optimization 
technique can result in more inefficient 
code if the statistics used in optimizing 
the program are not representative of the 
normal program flow. In addition, it is 
recommended that any optimization methods 
implemented be documented in the program. 



Rese quencing the Program 



The COBOL Procedure Division should be 
organized as follows: 

1. All frequently- used paragraphs or 
sections should be located near the 
routines that use them. 



All infrequently used paragraphs or 
sections should be grouped together 
and apart from frequently- used 
routines. 



The most frequently-referenced data 
items should be placed in the 
beginning of the Working-Storage 
Section. 



Insight into SYHDMP Output 



The area where dynamic symbolic dumps 
are to be used can be pointed to by the 
execution statistics. Knowledge of what 
area of code is executed and how often it 
is executed should give the user 
information on what sections should be 
further investigated. 



Common Expression Elimination 



This technique is designed to eliminate 
unnecessary arithmetic calculations. An 
arithmetic expression calculation is 
considered unnecessary if it represents a 
value calculated elsewhere that will always 
be used without modification. One such 
example would be an arithmetic expression 
whose operands are not redefined or 
reevaluated, but the expression is 
recalculated. 



Backward Movement 



This technique facilitates moving 
calculations and other operations from an 
area of code frequently executed to an area 
less frequently executed. For example, an 
expression calculated within a PERFORM 
procedure (using a Format 2, 3, or 4 
PERFORM statement) which always yields the 
same value for that PERFORM statement could 
be calculated inline or in another 
procedure which would be executed just 
prior to the regularly executed PERFORM 
procedure. Another example might be an 
expression which is calculated in many 
procedures which are often executed by way 
of a PERFORM in succession. This 
expression could be removed from all the 
procedures and calculated just once prior 
to the procedures. 
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Unrolling 



Procedures which are frequently executed 
may be expanded so that the stateaents 
within the procedure are repeated, with 
slight modification, to reduce the 
procedure overhead- For example, 

PERFORM YEARLY-GROSS-CALC VARYING 
WEEK-NO 

FROM 1 BY 1 UNTIL WEEK-NO 
GREATER THAN 52. 

YEARLY-GROSS-CALC. 

ADD GROSS-SALARY (WEEK-NO) 
TO YEARLY-GROSS 

could be replaced by 

PERFORM YEARLY-GROSS-CALC VARYING 
WEEK- NO 

FROM 1 BY H UNTIL WEEK-NO 
GREATER THAN 52. 

YEARLY-GROSS-CALC. 

ADD GROSS-SALARY (WEEK-NO) , 

GROSS-SALARY (WEEK-NO*1), 
GROSS-SALARY (WEEK-NO+2) , 
GROSS SALARY (WEEK-NO+3) TO 
YEARLY-GROSS. 

In addition, indexing might be useful in 
this exam pie. 



Jamming 



In some instances, two procedures can be 
merged into one procedure, thereby saving 
some procedure overhead. An example of 
this might be replacing 

MOVE TO WEEK-NUN. 

PERFORM YEA8LY-GROSS-CAL 52 TIMES. 

MOVE TO WEEK-NUM. 

PERFORM YEARLY-NET-CAL 52 TIMES. 



ADD 1 TO WEEK-NUM. 

ADD GROSS-SALARY (WEEK-NUM) 

TO YEARLY-GROSS. 

ADD NET-SALARY (WEEK-NUM) 

TO YEARLY-NET. 



Unswitchinq 



Procedures may contain tests that result 
in the same action for any set of 
executions of that procedure. In such a 
case, the test can be removed from the 
procedure and the procedure duplicated. 
For example, if "SWITCH" is not changed 
within the loop, replace 



KQUNT=0 
PERFORM 



JOBS-TOTAL-CAL JOB-NUM TIMES. 



JOB-TOTAL-CAL. 

ADD 1 TO KOUNT 

ADD JOB-COST (KOUNT) TO TOT AL- JOB-COST. 

IF SWITCH = ADD JOB-EXPENSE (KOUNT) 

TO TOTAL-EXPENSES ELSE 
ADD JOB-EXPENSE (KOUNT) OVERHEAD TO 

TOTAL-EXPENSES. 
ADD JOB-INCOME (KOUNT) TO TOTAL INCOME. 
IF SWITCH = ADD JOB-PROFIT (KOUNT) TO 

TOTAL-PROFITS ELSE 
COMPUTE TOTAL-PROFITS = TOTAL-PROFITS ♦ 

JOB-INCOME (KOUNT) - 
JOB-COST (KOUNT) - JOB-EXPENSE (KOUNT) 

- OVERHEAD. 



by 



KOUNT ~ 

IF SWITCH = 
PERFORM JOB-TOTAL-CAL-0 
JOB-NUM TIMES ELSE 
PERFORM JOB-TOTAL-CAL- 1 
JOB-NUM TIMES. 



by 



YEARLY-GROSS-CAL. 

ADD 1 TO WEEK-NUM. 

ADD GROSS-SALARY (WEEK-NUM) 

TO YEARLY-GROSS. 
YEARLY-NET-CAL. 

ADD 1 TO WEEK-NUM. 

ADD NET-SALARY (WEEK-NUM) TO 

YEARLY- NET. 



MOVE TO WEEK-NUM. 

PERFORM YEARLY-CAL 52 TIMES. 



YEARLY-CAL. 



JOB-TOTAL-CAL-0. 

ADD 1 TO KOUNT. 

ADD JOB-COST (KOUNT) TO TOTAL- JOB- CO ST. 

ADD JOB-EXPENSE (KOUNT) TO 

TOTAL/EXPENSES. 
ADD JOB-INCOME (KOUNT) TO TOTAL-INCOME. 
ADD JOB-PROFIT (KOUNT) TO 
TOTAL-PROFITS. 
JOB-TOTAL-CAL-1. 

ADD 1 TO KOUNT 

ADD JOB-COST (KOUNT) TO TOTAL-JOB-COST 

ADD JOB-EXPENSE (KOUNT) , OVERHEAD TO 

TOTAL- EXPENSE 
ADD JOB-INCOME (KOUNT) TO TOTAL-INCOME 
COMPUTE TOTAL-PROFITS = TOTAL-PROFITS ♦ 

JOB-INCOME (KOUNT) 
- JOB-COST (KOUNT) - JOB-EXPENSE 
(KOUNT) - OVERHEAD. 
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Incorporatin g Procedures Inline 



Based on nodule size, number of 
repetitions, modification activities, 
future expansion considerations, and 
frequency statistics, snail procedures can 
be moved inline to minimize overhead 
requirements. 



1. Unaligned decimal places in arithmetic 
or numeric comparison operands. 



Different size operands in moves, 
comparisons, or arithmetic operations. 



Mixed usage in arithmetic or numeric 
comparison operands. 



This technique is designed to replace 
many IF statements by one table- look-up 
statement, or by one computed GO TO 
statement. For example, if the same data 
item is tested in many successive IF 
statements to set the value of another data 
item to some constant, and the range of 
tested values of the original data item is 
limited, then a predetermined table of 
values could be used to assign the value 
of the second data item. Similarly, many 
consecutive statements of the form "IF 
data-item- 1 = so me- const ant GO TO 
some-procedure" could be replaced by one 
computed GO TO statement. 



4. Display usage in arithmetic operands 
or one numeric operand and one display 
operand in a comparison. 



5. SYNC missing for COUP or COMP-1, -2, 
or -4 items. 



Inefficient COMP type picture; that 
is, no sign or more than 9 digits in a 
COMP item and no sign, even number of 
digits, or more than 16 digits in 
COMP-3 items. 



7. Certain calls to object-time 
subroutines. 



E fficiency Gui d eli nes 



Indexing instead of subscripting and 
vice versa. 



Based on execution frequency statistics, 
the following types of coding 
inefficiencies may be removed. 



Noncomputational subscripts. 
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PROGRAMMING TECHNIQUES 



Some techniques for increasing the 
efficiency of a COBOL program are described 
in this chapter. It is divided into seven 
parts. The first four parts deal in 
general with coding a COBOL program. The 
fifth is concerned with the Report Writer 
feature, the sixth with table handling, and 
the seventh with queue structure 
description. 



GENERAL CONS IDERAT IONS 



Spacing the Sour ce Program .Listing 



There are four statements that can be 
coded in any or all of the four divisions 
of a source program: SKIP1, SKIP2, SKIP3, 
and EJECT. These statements provide the 
user with the ability to control the 
spacing of a source listing and thereby 
improve its readability. 



• All frequently used subroutines should 
be loaded near each other. This can be 
done via linkage editor control cards. 

• FDs for files that will be opened at 
the same time should be grouped 
together. 

• The most frequently referenced data 
items should be placed in the beginning 
of the Working Storage Section. 

• The COBOL Procedure Division should be 
organized generally as follows: 

a. All frequently used paragraphs or 
sections should be located near the 
routines that use them. 

b. All infrequently used paragraphs or 
sections should be grouped together 
and apart from frequently used 
routines. 



Coding considerations 



ENVIRONMENT DIVISION 



These suggestions will aid efficiency: 

* Use the RES option and place frequently 
used COBOL subroutines into the Paged 
Link Pack Area. 

* Avoid repetitive sequences of 

CALL 
CANCEL 
for the same subprograms. 

♦ If a short subprogram is referenced 
only once or twice (and is not an 
unusual situation routine) , then its 
code should be incorporated in the 
calling program, if convenient. 

• Subprograms should be loaded near the 
programs which use them. This can be 
done via linkage editor control cards. 

» segmentation in many cases is no longer 
desirable. 

• Data-names of constant value should be 
grouped together. Data-naies whose 
values vary during execution should 
also be grouped together and should be 
separate from those of constant value. 



APPLY WRITE-ONLY Clause 



To make optimum use of buffer space 
allocated when creating a physical 
sequential file with blocked V-mode 
records, the programmer may use the APPLY 
WRITE-ONLY clause for the file. Use of 
this option causes a buffer to be truncated 
only when the next record does not fit in 
the buffer. (If the APPLY WRITE-ONLY 
clause is not specified, the buffer is 
truncated when the maximum size record will 
not fit in the space remaining in the 
buffer.) When using APPLY WRITE-ONLY, all 
the WRITE statements must have FROM 
options. None of the subfields of the 
associated records may be referred to by 
procedure statements and they may not be 
the object of the DEPENDING ON option in an 
OCCURS clause. 



9J> M-S panned Re cords 



Except for APPLY WRITE-ONLY, ADVANCING, 
POSITIONING, and APPLY RECORD-OVERFLOW, all 
the options for variable length record 
files apply to spanned records. 
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APPLY RECORD-OVERFLOW Clause 



DATA DIVISION 



Tor non-VSAM files, the APPLY 
RECORD-OVERFLOW clause makes more efficient 
use of direct access storage space by using 
the Track overflow feature. If APPLY 
RECORD-OVERFLOW is specified, a record that 
does not fit on a track Mill be partially 
written on that track and the remainder 
will be written on the next available 
track. 



The use of the APPLY RECORD-OVERFLOW 
option requires that Track overflow be 
specified at system generation time. 



APPLY, CORE-I NDEX Clause 



OVERALL CONSIDERATIONS 



Ma xi mum Data Division Size 

The absolute maximum of the Data 
Division (excluding Linkage Section) 
is 1,044,480 bytes. (This includes 
File, Working-Storage, Communication, 
and Report Sections . ) Other maximum 
Lengths (in bytes) are: 

• data description entry — 32,7 67 

• variable length table — 32,767 

• fixed-length group item (including 
fixed-length table) in Working-Storage 
or Linkage Section — 131,071 



Prefixes 



To minimi 
sequential f 
programmer s 
clause. Use 
highest leve 
storage for 
speeds proce 
time needed 
volume. 



ze processing 
iles accessed 
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of this optio 
1 index to be 
input/output o 
ssing by elimi 
to search the 



time with indexed 
randomly, the 
APPLY CORE-INDEX 
n causes the 
brought into main 
perations. This 
nating the extra 
index on the 



Assign a prefix to each level-01 item in 
a program, and use this prefix on every 
subordinate item (except FILLER) to 
associate a file with its records and 
work-areas. For example, HASTER is the 
prefix used here: 



FILE SECTION. 

FD HASTES-INPUT-FILE 



BpAM-W File Organization 



01 MASTER-INPUT-RECORD. 



The use of BDAM-W for file organization 
results in less system generated coding 
than for BDAH-D. When BDAM-D is used and a 
WRITE statement is issued, extra code must 
be generated to compare the contents of the 
ACTUAL KEY of the WRITE statement with the 
key of the preceding READ statement to 
determine whether the system should add or 
update a record. If the keys are the same 
the record is updated. If the keys are 
different the record is added. 



BDAM-W eliminates this comparison step. 
The system adds a record when a WRITE 
statement is issued and updates a record 
when a REWRITE statement is issued. Wh2 



WORKING-STORAGE SECTION. 
01 MASTER-WORK-AREA. 

05 MASTER-PAYROLL PICTURE 9(3). 

05 HASTER-SSNO PICTURE 9<9). 



If files or work-areas have the same 
fields, use the prefix to distinguish 
between them. For example, if three files 
all have a date field, instead of DATE, 
DAT, and DA-TE, use MASTER-DATE, 
DETAIL-DATE, and REPORT-DATE. Using a 
unique prefix for each level-01 and all 
subordinate fields makes it easier for a 
person unfamiliar with the program to find 
fields in the program listing, and to know 
which fields are logically part of the same 
record or area. 



When asing the MOVE statement with the 
CORRESPONDING option and referring to 
individual fields, redefine or rename 
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"corresponding" names with the prefixed 
unique names. This technique eliminates 
excessive qualifying. For example: 

01 MST- WORK-ARE A. 

05 SAME-NAMES. {***) 

10 LAST-NAME PIC... 
10 FIRST- NAME PIC... 
10 PAYROLL PIC... 



RECORD CONTAINS Clause 



The programmer should use the RECORD 
CONTAINS integer CHARACTERS clause in order 
to save himself as well as any future 
programmer the task of counting the data 
record description positions. Also* the 
compiler can then diagnose errors if the 
data record description conflicts with the 
RECORD CONTAINS clause. 



05 DIFF-NAMES REDEFINES SAME-NAMES. 

10 MST-LAST-NAME PIC... 

10 MST-FIRST-NAME PIC... 

10 MST-PAYROLL PIC... 
01 RPT- WORK-AREA. 

05 SAME-NAMES. <***) 

10 PAYROLL PIC... 

10 FILLER PIC... 

10 FIRST-NAME PIC... 

10 FILLER PIC... 

10 LAST-NAME PIC... 



PROCEDURE DIVISION. 



COMMUNICATION SECTION 



The Communication Section of a COBOL 
program must be specified if the program is 
to take advantage of the Teleprocessing 
Feature (TP) . Through the inclusion of 
Communication Description (CD) entries, the 
programmer establishes communication 
between the COBOL object program and the 
Message Control Program (MCP) . 



IF MST-PAYROLL IS EQUAL TO HDQ-PAYROLL 

AND MST-LAST-NAME 

IS NOT EQUAL TO PRRV -LAST-NAME 

MOVE CORRESPONDING 

MST-WORK-AREA 

TO RPT-BORK-AREA. 



Note: Fields marked with a triple asterisk 
{***) in the foregoing listing must have 
exactly the same names for their 
subordinate fields in order to be 
considered corresponding. The same names 
must not be the redefining ones, or they 
will not be considered to correspond. 



Leve l Number s 



The programmer should use widely 
incremented level numbers, i.e., 01, 05, 
10, 15, etc., instead of 01, 02, 03, 04, 
etc., in order to allow room for future 
insertions of group levels. For 
readability, indent level numbers. Use 
level-88 numbers for codes. Then, if the 
codes must be changed, the Procedure 
Division coding for tests need not be 
changed. 



CD Entries 



When specified, the communication 
Section must contain at least one CD entry. 
For example, a single CD entry would be 
sufficient for applications with either an 
input or an output message but not both. A 
COBOL TP program that is both to receive 
and to send messages must contain at least 
two 1 CD entries, as below. 

CD cd-name FOR INPUT- 
CD cd-name FOR OUTPUT. 

The CD entry may instead be pre-written 
and included in the user-created library. 
The programmer may then include the entry 
in a COBOL program by means of a COPY 
statement. 

CD cd-name COPY library-name. 

The input CD contains such information as 
input queue and sub-queue names, message 
date and time, the source, the message text 
length, the end key, the message status 
key, and the message count. The output CD 
contains the text length, the destination 
count, a status key and error key (both 
possibly repeating), and the name of the 
output queue. For information about the CD 
formats possible, see the publication £BM 
IS COBOL_£or_Q.g/IS . 



FILE SECTION 



* Multiple input and output CD entries may 
be specified. 
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Note; The required inclusion of the 
parameter DATE=YES in all input TPROCESS 
entries whose destination is a COBOL 
program results in the placing of the date 
and time of message entry in the input CD 
(see the section "Additional Interface 
Considerations" in the chapter entitled 
"Using the Teleprocessing Feature") . 



Alternatively, the programmer may locate 
this section in object- time dumps by 
including the following two statements in 
the program, in the order given: 

77 FILLER PICTURE X{44), VALUE "PROGRAM 

XXXXXXXX WORKING-STORAGE BEGINS HERE". 



01 



FILLER PICTURE X (42) , VALUE "PROGRAM 
XXXXXXXX WORKING-STORAGE ENDS HERE". 



WORKING-STORAGE SECTION 



Sepa rate Modules 



In a large program, the programmer 
should plan ahead for breaking the programs 
into separately compiled modules, as 
follows: 



1. 



2. 



3. 



4. 
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Areas that do not have VALUE clauses 
should be separated from areas that do 
need VALUE clauses. VALUE clauses 
(except for level-88 items) are 
invalid in the Linkage section. 

When the Working-Storage section is 
one level-01 item with no VALUE 
clauses, the COPY statement can easily 
be used to include the item as the 
description of a Linkage Section in a 
separately compiled module. 

See "Use of Segmentation Feature" for 
more information on how to modularize 
the Procedure Division of a COBOL 
program. 



L ocating the Working-Storage Sectio n in 
Dumps 



These two nonnumeric literals will 
appear in all dumps of the program, 
delineating the Working-Storage Section, 
The prog ram- name specified in the 
PROGRAM-ID clause should replace the 
XXXXXXXX in the literal. 



DATA DESCRIPTION 



The Procedure Division operations that 
most often require adjustment of data items 
include the MOVE statement, the IF 
statement when used in a relation test, and 
arithmetic operations. Efficient use of 
data description clauses, such as 
REDEFINES, RENAMES PICTURE, and USAGE, 
avoids the generation of extra code. 



RJ.pjFIflS5_£lause 



REUSING DA TA A REAS: The main storage area 
can be used more efficiently by writing 
different data descriptions for the same 
data area. For example, the coding that 
follows shows how the same area can be used 
as a work area for the records of several 
input files that are not processed 
concurrently: 

WORKING- STORAGE SECTION. 
01 WORK-AREA-FILE 1. 

(largest record description for FILE1) 



01 W0RK-AREA-FILE2 REDEFINES 
WORK-ARE A- FILE 1. 
(largest record description for FILE2) 



When any one or more of the options 
PMAP, CLIST, and DMAP are specified, both 
the location and the length (in 
hexadecimal) of the Working-Storage 
Section, if any, are provided (see the 
section "Options for the Compiler" in the 
chapter entitled "Job Control Procedures") 



ALTERNATE GROUPINGS AND DESCRIPTIONS : 
Program data can often be described more 
efficiently by providing alternate 
groupings or data descriptions for the same 
data. For example, a program refers to 
both a field and its subfields, each of 
which is more efficiently described with a 
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different usage. This can be done with the 
REDEFINES clause as follows: 

01 PAYROLL- RECORD. 

05 EMPLOYEE-RECORD PICTURE X<28). 
05 EMPLOYEE-FIELD REDEFINES 

EMPLOYEE- RECORD . . 

10 NAME PIC X(23) . 

10 NUMBERX PIC S9 (5) COMP SYNC, 

05 DATE-RECORD PICX(10). 



15 FILE- 3 PICTURE X. 
66 SUM-X RENAMES FIELD-X. 
66 SUM-XY RENAMES FIELD-X THRU FIELD-Y. 
66 SUM-XXZ RENAMES FIELD-X THRU FIELD-Z. 

If each level- 15 item contained either an A 
or an I, a programaer could find out how 
many files contained an A by doing a 
complete tally of files in OUT-REC: 

EXAMINE SUM-XYZ TALLYING ALL "A" 



As an example of different data 
descriptions specified for the saae data, 
the following illustrates how a table 
(TABLEA) can be initialized: 

05 VALUE-A. 

10 A1 PICTURE S9{9) COMPUTATIONAL 

VALUE IS ZEROES. 
10 A2 PICTURE S9{9) COMPUTATIONAL 

VALUE IS 1. 



Or a programmer might just want to tally 
the files in FIELD-X: 

EXAMINE SUM-X TALLYING ALL "A" 

In short, renaming fields can lead to 
better utilization of coding, storage, and 
time by facilitating the streamlining of 
Procedure Division operations. 



10 A100 PICTURE S9{9) 

COMPUTATIONAL VALUE IS 99. 



PICTURE Clause 



05 TABLEA REDEFINES VALUE-A 

PICTURE S9 (9) COMPUTATIONAL 
OCCURS 10 TIMES- 

lote: Caution should be exercised when a 
redefining or redefined item is used as a 
subscript. If the value of a redefining 
item is changed in the Procedure Division 
and the redefined item is used as a 
subscript, or vice versa, then no new 
calculation for the subscript is performed. 



RENAMES Clause 



DECIMAL-POINT ALIGNMENT: Procedure 
Division operations are most efficient when 
the decimal positions of the data items 
involved are aligned. If they are not, the 
compiler generates instructions to align 
the decimal positions before any operations 
involving the data items can be executed. 
This is referred to as sca ling. 

Assume, for example, that a program 
contains the following instructions: 

WORKING-STORAGE SECTION. 
77 A PICTURE S999V99. 
77 B PICTURE S99V9. 



By permitting a programaer to rename 
various fields, the RENAMES clause enables 
alternate, possibly overlapping, groupings 
of elementary data. The following example 
shows how three fields of a record can be 
renamed: 



PROCEDURE DIVISION. 



ADD A TO B. 



01 OUT-REC. 

05 FIELD-X. 

10 SUMMARY-GROUPX. 

15 FILE-1 PICTURE X. 
15 FILE-2 PICTURE X. 
15 FILE-3 PICTURE X. 
05 FIELD-Y. 

10 SUMMARY-GROUPY. 

15 FILE-1 PICTURE X 
15 FILE-2 PICTURE X. 
15 FILE-3 PICTURE X. 
05 FIELD-Z. 

10 SUMMARY-GROUPZ. 

15 FILE-1 PICTURE X. 
15 FILE-2 PICTURE X. 



Time and internal storage space are 
saved by defining B as: 

77 B PICTURE S99V99. 

If it is inefficient to define B 
differently, a one-time conversion can be 
done, as explained in "Data Format 
Conversion." 

FIELDS OF UNEQUAL LENGTH: Hhen a data item 
is moved to another data item of a 
different length, the following should be 
considered: 
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If the items are external decimal 
items, the compiler generates 
instructions to insert zeros in the 
high-order positions of the receiving 
field when it is the larger. 
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Use of Sign: The absence or presence of a 
plus or minus sign in the description of an 
arithmetic field often can affect the 
efficiency of a program. The following 
paragraphs discuss some of the 
considerations. 



in F is treated as positive, but is 
not an overpunch. 

3. An invalid configuration. If an 
internal or external decimal item 
contains an invalid configuration in 
the sign position, and if the item is 
involved in a Procedure Division 
operation, the program will be 
abnormally terminated. 

Items for which no S has been specified 
(u nsigned item s) are treated as absolute 
values. Whenever a value (signed or 
unsigned) is stored in, or moved in an 
elementary move to an unsigned item, a 
hexadecimal F is stored in the sign 
position of the unsigned item. For 
example, if an arithmetic operation 
involves signed operands and an unsigned 
result field, compiler-generated code will 
insert an F in the sign position of the 
result field when the result is stored. 



De ci mal Item s; The sign position in an 
internal or external decimal item can 
contain: 

1. A plus or minus sign. If S is 

specified in the PICTURE clause, a 
plus or minus sign is inserted when 
either of the following conditions 
prevails: 

a. The item is in the Working-Storage 
Section and a VALUE clause has 
been specified. 

b. A value for the item is assigned 
as a result of an arithmetic 
operation during execution of the 
program. 



For internal and external decimal items 
used as input, it is the user's 
responsibility to ensure that the input 
data is valid. The compiler does not 
generate a test to ensure that the 
configuration in the sign position is 
valid. 
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A hexadecimal F. If S is not 
specified in the PICTURE clause, an F 
is inserted in the sign position when 
either of following conditions exists: 

a. The item is in the Working- Storage 
Section and a VALOE clause has 
been specified. 

b. A value for the item is developed 
during the execution of the 
program. 



SIGN Clause 



This clause, which specifies both the 
position and the mode of the operational 
sign for a numeric data description entry, 
is required only when an explicit 
description of the sign's properties is 
necessary. The SIGN clause may be 
specified for either a numeric data 
description entry whose PICTURE contains 
the character S or a group item that 
contains at least one such numeric data 
description entry. 

The numeric data description entries to 
which the SIGN clause applies must be 
described, implicitly or explicitly, as 
USAGE IS DISPLAI. Only one SIGN clause may 
be associated with any given numeric data 
description entry. 

The format of the SIGN clause is as 
follows: 
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(leading i 
sign is < > [ separate character] 
(trailing) 

Use_.gf the SEPARATE, CHARACTER Option : T he 
programmer can elect to consider the 
character S in the PICTURE character string 
as a separate character or not, as he 
chooses. If the SEPARATE CHARACTER option 
is specified: 

♦ The position of the character S is not 
taken to be a digit position. 

• The character S is counted in 
determining the size of the data item. 

* The characters •♦* and ' -* are used for 
the positive and the negative 
operational signs, respectively. 

• If neither the character • *• nor the 
character *-* is present in the data at 
object time, an error takes place and 
the program ABENDS. 

Whether or not the SEPARATE CHARACTER 
option is in effect, the operational sign 
is assumed to be associated with either the 
LEADING or the TRAILING digit position, as 
specified, of the elementary numeric data 
item. 



USAGE Clause 



The following eight cases show how data 
conversions are handled on mixed elementary 
items for names, data comparisons, and 
arithmetic operations. Moves to and from 
group items, without the CORRESPONDING 
option, as well as comparisons involving 
group items, are done without conversion. 



Numeric DISPLAY to COMPUTATIONAL- 3 ; 



20-.l2ie_£§i§5 Converts DISPLAY data to 
COMPUTATIONAL-3 data. 



To Compare Dat a: Converts DISPLAY data 
to~C0HPUTATl0NAL-3 data. 

To perf orm Ar ithmetic operations : 
Converts DISPLAY data to COMPUTATIONAL-3 
data. 



Nu meri c DISPLAY to COMPUTATIONAL: 

To Move Dat a: Converts DISPLAY data to 
COMPUTATIONAL-3 data and then to 
COMPUTATIONAL data. 

To Com pa re Data : Converts DISPLAY to 
C0MPUTATI0NAL-3 and then to 
COMPUTATIONAL or converts both DISPLAY 
and COMPUTATIONAL data to 
COMPUTATIONAL-3 data. 



This clause should be written at the 
highest level possible. 



DATA FORMAT CONVERSION : 



involving mi 
formats regu 
format. Thi 
storage is u 
increased. 
move data to 
any necessar 
the indicate 
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If it is impractical 
data formats throughout 
two data items of differ 
frequently used together 
conversion can be effect 
if A is defined as a COM 
B as a COMPUTATIONAL-3 i 
to a work area that has 
COMPOTATIONAL-3. This ffi 
in A to be converted to 
Whenever A and B are use 
Division operation, refe 
to the work area rather 
this technique, the conv 
only once, instead of ea 
operation is performed. 



to use the same 
a program, and if 
ent formats are 
, a one- time 
ed. For example, 
PUTATIQNAL item and 
tea, A can be moved 
been defined as 
ove causes the data 
COMPUTATIONAL- 3. 
d in a Procedure 
rence can be made 
than to A. Using 
ersion is performed 
ch time an 



To Perform Arithmetic O pera ti o ns : 
Converts DISPLAY data to COMPUTATIONAL- 3 
or COMPUTATIONAL data. 



COMPUTATIONAL-3 tO_ COMPUTATIONAL : 

To Move Data: Moves COMPUTATIONAL-3 
data to a work field and then converts 
COMPUTATIONAL-3 data to COMPUTATIONAL 
data. 

To Compare Data: Converts COMPUTATIONAL 
data to COMPUTATIONAL-3 or vice versa, 
depending on the size of the field. 

To Perform Arithmetic operations : 
Converts COMPUTATIONAL data to 
COMPUTATIONAL-3 or vice versa, depending 
on the size of the field. 



COMPUTATIONAL %o CQMPUTATIQpAL-3: 

To Hove Data: Converts COMPUTATIONAL 
data to COMPUTATIONAL-3 data in a work 
field, then moves the work field. 

To Compare Data : Converts COMPUTATIONAL 
to COMPUTATIONAL-3 data or vice versa, 
depending on the size of the field. 
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Figure 107. Data Format Conversion 
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To Perform Arithmetic Operations : 
Converts COMPUTATIONAL to 
COMPUTATIONAL-3 data or vice versa, 
depending on the size of the field. 

COMPUTATIONAL to Numeric DISPLAY : 

To Hove Data: Converts COMPUTATIONAL data 
to COMPUTATIONAL-3 data and then to DISPLAY 
data. 



To C ompare Dat a: Converts DISPLAY to 
COMPUTATIONAL or both COMPUTATIONAL and 
DISPLAY data to CQMPUTATIONAL-3 data, 
depending on the size of the field. 



To Perform Arithmetic O perations : 
Depending on the size of the field, 
converts DISPLAY data to COMPUTATIONAL 
data, or both DISPLAY and COMPUTATIONAL 
data to COMPUTATIONAL- 3 data in which case 
the result is generated in a 
COMPUTATIONAL-3 work area and then 
converted and moved to the DISPLAY result 
field. 



CQMPUTATIONAL-3 to Numeric DISPLAY : 



SP^ cj.a l_.C,onsider n atiops_for_D^ §PLA Y^nd 
COMPUTAf IONAL^Fields 



NUMERIC DISPLAY FIELDS: Zeros are not 
inserted into numeric DISPLAY fields by the 
instruction set. When numeric DISPLAY data 
is moved, the compiler generates 
instructions that insert any necessary 
zeros into the DISPLAY fields. When 
numeric DISPLAY data is compared, and one 
field is smaller than the other, the 
compiler generates instructions to move the 
smaller item to a work area where zeros are 
inserted. 

COMPUTATIONAL- 1 AND CQMPUTATI0NAL-2_FIELDS : 
If an arithmetic operation involves a 
mixture of short- precis ion and 
long-precision fields, the compiler 
generates instructions to expand the 
short- precision field to a long- precision 
field before the operation is executed. 

COMPUTATIONAL-3 FIELDS: The compiler does 
not have to generate instructions to insert 
high-order zeros for ADD and SUBTRACT 
statements that involve COMPUTATIONAL-3 
data. The zeros are inserted by the 
instruction set. 



2fi_HQve_Data: Converts COMPDTATIONAL-3 
data to DISPLAY data. 



Da ta F ormats . in ,, t hereon puter 



To Compare Data: Converts DISPLAY data to 
COMPUTATIONAL-3 data. The result is 
generated in a COMPUTATIONAL-3 work area 
and is then converted and moved to the 
DISPLAY result field. 



Num eric DISPLA Y to Numeric DISPLAY : 



The various COBOL data formats and how 
they appear in the computer in EBCDIC 
{Extended Binary-Coded-Decimal Interchange 
Code) format are illustrated by the 
following examples. More detailed 
information about these data formats 
appears in the publication IM_S_ystem^370 
Principles of operation . Order 
No. GA22-7000. 



To Per for m Arithmetic Operations: Converts 
all DISPLAY~data to 

COMPUTATIONAL-3 data. The result is 
generated in a COMPUTATIONAL-3 work area 
and is then converted to DISPLAY and moved 
to the DISPLAY result field. 

External Flo ating- Point to Any Other : When 
an external floating-point item is to be 
used in an airthmetic operation or in data 
manipulation, precision errors may occur 
due to required conversions. 



Numeric DISPLAY (Extern al D ecimal ) : 
Suppose the value of an item is -1234, and 
the PICTURE and USAGE are: 

PICTURE 9999 DISPLAY. 



or 



PICTURE S9999 DISPLAY. 

The item appears in the computer in the 
following forms respectively: 



Internal Floatinq-Po 
an item described as 
C0HPDTATI0NAL-2 (int 
is used in an operat 
format, the item in 
is always converted 
floating-point. If 
floating-point resul 
the format of the ot 



i nt to Any Other : When 

COMPUTATIONAL- 1 or 
ernal floating-point) 
ion with another data 
the other data format 
to internal 

necessary, the internal 
t is then converted to 
her data item. 



| Fl | F2 j F3 | F4 | 
L X X X J 



Byte 

| Fl | F2 | F3 | D4 | 
L X X X J 



Byte 
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Hexadecimal F is treated arithmetically as 
plus in the low-order byte. The 
hexadecimal character D represents a 
negative sign. 



J 1111 J 1011 | 0010 | 1110 { 



sxgn 
position 



COMPUTATIONAL- 3 (Internal Decimal) : 
Suppose the value of an item is +1234, and 
its PICTURE and USAGE are: 

PICTURE 9999 C0MPUTATI0NAL-3. 

or 

PICTURE S9999 COMPUTATIONAL-3. 



The item appears in the computer in the 
following forms, respectively: 

j 01 | 23 | 4F | 

L X L— J 

Byte 

| 01 | 23 | 4C ] 
L J i____J 

Byte 

Hexadecimal F is treated arithmetically as 
positive. The hexadecimal character C 
represents a plus sign. 

Note: since the low-order byte of an 
internal decimal number always contains a 
sign field, an item with an odd number of 
digits can be stored more efficiently than 
an item with an even number of digits. 
Note that a leading zero is inserted in the 
foregoing example. 



COMPUTATIONAL fBina ry) : Suppose the value 
of an item is 1234, "and its PICTUBE and 
USAGE are: 

PICTURE S9999 COMPUTATIONAL. 

The item appears in the computer in the 
following form: 

i 0000 | 0100 1 1101 ! 0010 J 

i 1 1 1 1 

sign 
position 



A 0-bit in the sign position means the 
number is positive. Negative numbers are 
represented in two*s complement form; thus, 
the sign position of a negative number will 
always contain a 1-bit. 

For example -1234 would appear as 
follows: 



Binary Item,, Manipulation: A binary item is 
allocated storage ranging from one halfword 
to two words, depending on the number of 9s 
in its PICTURE. Figure 108 is an 
illustration of how the compiler allocates 
this storage. Note that it is possible for 
a value larger than that implied by the 
PICTUBE to be stored in the item. For 
example, PICTURE S9{4) implies a maximum 
value of 9,999, although it could actually 
hold the number 32,767. 

Because most binary items are 
manipulated according to their allotted 
storage capacity, the programmer can ignore 
this situation. For the following reasons, 
however, there are some cases where he must 
be careful of his data: 

1. When the ON SIZE ERROR option is used, 
the size test is made on the basis of 
the maximum value allowed by the 
picture of the result field. If a 
size error condition exists, the value 
of the result field is not altered and 
control is given to the imperative 
statements specified by the error 
option. 

2. Hhen a binary item is displayed or 
exhibited, the value used is a 
function of the number of 9s specified 
in the PICTURE clause. 

3. Hhen the actual value of a positive 
number is significantly larger than 
its picture value, a 1 could result in 
the sign position of the item, causing 
the item to be treated as a negative 
number in subsequent operations. 

Figure 109 illustrates three binary 
manipulations. In each case, the result 
field is an item described as PICTURE S9 
COMPUTATIONAL. One half word of storage has 
been allocated; and no ON SIZE ERROR option 
is involved. Note that if the ON SIZE 
ERROR option had been specified, it would 
have been executed for cases B and C. 

COMPUTATIONAL- 1 or , CpHEPTATIOH AL-2 
f F loating Poin t) : suppose the value of an 
item is +1234, ""and that its USAGE is 
COMPUTATIONAL- 1 , the item appears in the 
computer in the following form: 



10} 100 0011J0100 1101 0010 0000 0000 OOOOJ 

I I 1 ; » 



S 1 



7 8 



31 
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PICTURE 



Maximum Working Value 



Assigned Storage 



\ S9 through S9 {U) 

I 

|S9 (5) through S9<9) 

\ 

JS9 (10) through S9 (18) 

i : 



| 32,767J one halfword 

I I 

j 2,147,483,647j one fullword 

i i 

I 9,223,372,036,854 # 775,807| two fullwords 

_i 1 . 



Figure 108- Relationship of PICTURE to storage Allocation 



| Case 
I 



Hexadecimal Result of I 
Binary Calculation J 



Decimal } Actual Decimal Value | Display or | 
Equivalent J in Halfword of Storage j Exhibit Value J 



0008 



+ 8 



I B 



000A 



10 



+ 10 



J 



C350 



I 



50000 



-15536 



Figure 109. Treatment of Varying Values in a Data Item of PICTURE S9 



S is the sign position of the number. 

A 0-bit in the sign position indicates 
that the sign is plus. 

A 1-bit in the sign position indicates 
that the sign is minus. 

Bits 1 through 7 are the exponent 
(characteristic) of the number. 

Bits 8 through 31 are the fraction 
(mantissa) of the number. 



maintain and document. In addition, 
modularization makes it simple to break 
down a program using the segmentation 
feature, thereby resulting in a more 
efficient segmented program. 
Modularization of the Procedure Division 
involves organizing it into at least three 
functional levels: a main-line routine, 
processing subroutines, and input/output 
subroutines. 



Main-Line Routine 



This form of data is 
floating-point. The exa 
short- precision floating 
(COMPUTATIONAL- 1) . In 1 
(COMPUTATIONAL-2) , the f 
56 bits. (For a detaile 
floating-point represent 
publication IBM System/3 



referred to as 
mple illustrates 
-point data 
ong-precision 
raction length is 
d explanation of 
ation, see the 
70 Prin ciples of 



Operation. Order No. GA22-7000. 



PROCEDURE DIVISION 



A program can often be made more 
efficient or easier to debug in the 
Procedure Division with some of the 
techniques described below. 



MODULARIZING THE PROCEDURE DIVISION 



When the Procedure Division is 
modularized, programs are easier to 



This routine should be short, simple, 
and contain all the major logical decisions 
of the program. This routine controls 
which second-level subroutines are executed 
and in what order. All second-level 
subroutines should be invoked from the 
main-line routine by PERFORM statements. 



Processing Subrou tines 



These should be broken down into as many 
functional levels as necessary, depending 
on the complexity of the program. These 
must be completely closed subroutines, with 
one entry point and one exit point. The 
entry point should be the first statement 
of the subroutine. The exit point should 
be the EXIT statement. The processing 
subroutines can perform only lower level 
subroutines; return to the higher level 
subroutine {processing subroutine) must be 
made by a GO TO statement, which references 
the EXIT statement. 
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Input /Output Subroutines 



USE OF THE OPSI SWITCHES 



These should be the lowest level 
subroutines, since all higher level 
subroutines should have access to them. 
There should be one OPEN subroutine and one 
CLOSE subroutine for the program, and only 
one functional (BEAD or WRITE) subroutine 
for each file. One HEAD or WRITE 
subroutine per file, which is always 
performed, has several advantages: 



1. Coding can be added to count records 
on a file, transform blanks into 
zeros, check for 9s padding, etc. 



Input and output files can be 
reformatted without changing the logic 
of the program. 



DEBUG statements can be added during 
testing to create input or to DISPLAY 
formatted output, instead of having to 
create a test file. 



COLLATING SEQUENCES 



The combination of th 
SEQUENCE clause and the 
alphabet-name clause (s) 
programmer flexibility i 
altering the collating s 
following operations: t 
non-numeric comparisons, 
SEARCH ALL, and SORT/SEE 
used may be EBCDIC (deno 
which is also the defaul 
as STANDARD- 1), or one o 
programmer-defined alter 
EBCDIC seguence. 



e PROGRAM COLLATING 
SPECIAL NAMES 
offers the 
n establishing or 
eguence used in the 
he various forms of 

HIGH/LOW-VALUE, 
GE. The alphabet 
ted as NATIVE, 
t) , ASCII (denoted 
r more 
ations of the 



The alphabet identified through the 
PROGRAM COLLATING SEQUENCE clause will be 
used for all occurences of non- numeric 
compares, HIGH/LOW-VALUE, and SEARCH ALL. 
However, each separate SOBT/MERGE operation 
can override that general specification by 
including its own COLLATING SEQUENCE 
clause. 

For QSAM files, the CODE- SET clause of 
the FD statement can be used to identify 
the file as being either EBCDIC or ASCII. 
When an ASCII file is identified in this 
manner, the corresponding DD card need not 
specify DCB= (GPTCD=Q.. .) or 
DCB=(RECFM=D...) . 



The flexibility of programs can be 
greatly increased through use of the 
execution-time switches UPSI-O, 
UPSI-1,...UPSI-7 (see "Options for 
Execution" in the section "Job Control 
Procedures") . A program can be written to 
deal with many potential situations, and 
then directed (when it is to begin 
execution) as to which particular 
situations are current during that run. 



For 
to rea 
proced 
on cer 
report 
These 
detera 
know o 
by usi 
can be 

The 
writte 
tests 
UPSI s 
produc 
everyd 
instal 
parame 
to zer 
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sets t 
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example, a program might be designed 
d File A and create File B; these two 
ures are always to be done. However, 
tain irregular occasions, a special 

is also to be written to File C. 
special occasions are externally 
ined — the program could not normally 
f or internally determine them. But 
ng an UPSI switch, this difficulty 

overcome. 



code for the production of File C is 
n predicated on an IF statement that 
the associated condition name of an 
witch: if on, the special report is 
ed; if off, it is skipped. For 
ay executions of the program, the 
lation supplies the UPSI object-time 
ter with that particular switch set 
o. When occasion demands that the 
1 report be printed, the installation 
he UPSI object-time parameter switch 
, and the program's logic then writes 
e report. 



Because there are eight UPSI switches, 
controlled variation of a much more complex 
nature can be obtained by a user. 



INTERCEPTING I/O ERRORS 



COBOL offers a variety of techniques the 
programmer can employ to intercept and 
handle I/O error situations. Use of these 
techniques (INVALID KEY, USE AFTER 
ERROR/EXCEPTION, and FILE STATUS) gives a 
programmer not only the power to prevent 
abnormal termination, but also flexibility 
in his response. FILE STATUS — valid for 
VSAM and QSAM files — can be used separately 
or in combination with one of the other two 
techniques. COBOL automatically fills in 
the key field immediately after every I/O 
operation, so that the program can be 
designed to examine it and take action 
accordingly. (If FILE STATUS is specified 
but not interrogated by a program after an 
I/O operation, results are unpredicatble.) 
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Erro rs That Bay Es cape Detection 



If a logic erro 
attempts a READ or 
unopened file, an 
declarative will n 
an error occurs wh 
closed but not reo 
ERROR declarative 
However, such a si 
circumvented by us 
for successful ope 
READ/WRITE. 



r occurs because the user 

WRITE against an 
associated USE ERROR 
ot get control. If such 
en the file has been 
pened, the wrong USE 
may get control, 
tuation can be 
ing FILE STATUS to test 
n before performing the 



2. the length of the scaled divisor plus 
the length of the scaled dividend is 
greater than 16 bytes. The lengths of 
the operands are internal decimal. 



3. the sca led dividend is greater than 30 
digits. (A scaled dividend is a 
number that has been multiplied by a 
power of ten in order to obtain the 
desired number of decimal places in 
the quotient.) 



INTERMEDIATE RESULTS 



Intermediate Results greater than 30 Digits 



The compiler treats arithmetic 
statements as a succession of operations 
and sets up intermediate result fields to 
contain the results of these operations. 
Examples of such statements are the 
arithmetic statements, and statements 
containing arithmetic expressions. The 
publication IBM VS COBOL for OS/VS 
describes the algorithms used by the 
compiler to determine the number of places 
reserved for intermediate result fields. 



Intermediate, Results and Binary Data Items 



If an operation involving binary 
operands requires an intermediate result 
greater than 18 digits, the compiler 
converts the operands to internal decimal 
before performing the operation. If the 
result field is binary, the result will be 
converted from internal decimal to binary. 

If an intermediate result will not be 
greater than nine digits, the operation is 
performed most efficiently on binary data 
fields. 



Whenever the number of digits in a 
decimal intermediate result is greater than 
30, the field is truncated to 30 digits. A 
warning message will be generated at 
compile time, and program flow will not be 
interrupted at execution time. This 
truncation may cause a result to be 
incorrect. 



If binary or internal decimal data is in 
accord with its data description, no 
interrupt can occur because of an overflow 
condition in an intermediate result. This 
is due to the truncation described in the 
preceding paragraph. 



If the possibility exists that an 
intermediate result field may exceed 30 
digits, truncation can be avoided by the 
specification of floating-point operands 
(CQ8PUTATI0NAL-1 or C0HPUTATI0NAL-2) ; 
however, accuracy may not be maintained. 



Intermediate Re sults and Floating-Point 
Data Items 



Intermediate Results and C OBOL L ibrary 
Subroutines 



If a decimal multiplication operation 
reguires an intermediate result greater 
than 30 digits, a COBOL library subroutine 
is used to perform the multiplication. The 
result of this multiplication is then 
truncated to 30 digits. 

A COBOL library subroutine is used to 
perform division if: 

1. the scaled divisor is equal to or 
greater than 15 digits. 



If a floating-point operand has an 
intermediate result field in which exponent 
overflow occurs, the job will be abnormally 
terminated. 

If the exponent is a floating-point 
item or has a PICTURE specifying decimal 
places, the subroutine ILBOFPWO is 
called. and the exponentiation is executed 
in floating-point arithmetic. 
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Note: The base is always treated as a only a floating-point field may produce a 
positive number, regardless of sign, and slightly different final answer than a 
the answer is always a positive number. similar COMPUTE or DIVIDE statement which 
Caution should therefore be exercised stores its intermediate results in both a 
when using noninteger exponents. floating-point and a fixed point field. 

This is because of the different precisions 
of the fixed- and floating-point fields. 
Cau tion; A COMPOTE or DIVIDE statement 
which stores its intermediate results in 
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int erm edia te Resu lts and the ON SIZE ERROR 
Opt ion 



The ON SIZE ERROR option applies only to 
the final calculated results and not to 
intermediate result fields. 



COBOL processing environment. That is, a 
CANCEL statement issued for a subprogram 
that has been dynamically loaded causes the 
storage occupied by the subprogram to be 
freed. As a result, a subsequent call to 
the subprogram functions as if it were the 
first. 



VERBS 



CANCEL CALLED-PROGRAM. 



CALL, Sta teme nt 



The CALL 
between a CO 
more COBOL s 
subprograms, 
entered eith 
Procedure Di 
When a subpr 
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specified as 
separate loa 
the CALL sta 
load a subpr 
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The first 
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Any subseque 
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same copy of 
last-used st 
(see the sec 
Statement"). 
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The ON OVERFLOW phrase can be included 
in the CALL statement to circumvent 
abnormal termination when there is 
insufficient main storage available for 
dynamically loading the called program. 
The imperative statement associated with 
the ON OVERFLOW will gain control in such a 
situation, allowing the user to handle the 
problem in a manner of his own choosing and 
continue execution. (The conditions 
handled by ON OVERFLOW are equivalent to 
the following completion codes: 106C, 804, 
80A, and 878.) 

For examples of both static and dynamic 
CALL statements, see the section "Dynamic 
Subprogram considerations" in the chapter 
entitled "Calling and Called Programs." 



N_ote: A program other than the original 
caller may issue a CANCEL statement 
referring to a called program. 



CLOSE statement 



There are two ways in which to use the 
CLOSE statement when closing several files: 

CLOSE DETAIL-FILE MASTER-FILE. 

or 

CLOSE DETAIL-FILE. 
CLOSE MASTER-FILE. 

Each CLOSE statement for a file requires 
the use of a storage area that is directly 
proportional to the number of files being 
closed. Closing more than one file with 
the same statement is faster than when 
using a separate statement for each file. 
However, separate statements require less 
storage. 



COMPOTE Statement 



The use of the COMPUTE statement 
generates more efficient coding than does 
the use of individual arithmetic statements 
because the compiler can keep track of 
internal work areas and does not have to 
store the results of intermediate 
calculations. It is the user's 
responsibility, however, to insure that the 
data is defined with the level of 
significance required in the answer. 



CANCEL Statement 



The CANCEL statement permits dynamic 
deletion of COBOL subprograms from the 



IF Statement 



Nested and compound IF statements should 
be avoided as the logic is difficult to 
debug. 
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MOVE Statement 



PERFORM Verb 



When a MOVE statement with the 
CORRESPONDING option is executed, data 
items are considered COR RESPONDING only if 
their respective data names are the same, 
including all implied qualification, up to, 
but not including, the data-names used in 
the MOVE statement itself. 



For example. 
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PERFORM is a useful verb if the 
programmer adheres to the following rules: 
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The statement MOVE CORRESPONDING AA TO XX 
will result in moving CC and DD but not FF 
because FF of EE does not correspond to FF 
of YY). 

Note: The other rules for MOVE 
CORRESPONDING, of course, must still be 
satisfied. 



NOTE Statement 



An asterisk {*) should be used in place 
of the NOTE statement, because there is the 
possibility that when NOTE is the first 
sentence in a paragraph, it will 
inadvertently cause the whole paragraph to 
be treated as part of the NOTE. 



OP EN Statement 



There are two ways in which to use the 
OPEN statement when opening several files: 

OPEN INPUT INFILE UPDATES OUTPUT OUTFILE 

or 

OPEN INPUT INFILE 
OPEN INPUT UPDATES 
OPEN OUTPUT OUTFILE 



Each OPEN statement for a file requires 
the use of a storage area that is directly 
proportional to the number of files being 
opened. Opening more than one file with 
the same statement is faster than using a 
separate statement for each file. However, 
separate statements require less storage. 



Always either P 
THRU routine-na 
section-name, 
paragraph-name 
the programmer 
program. For e 
must be broken 
the programmer 
statement to de 
this paragraph 
the PERFORM sta 
statements refe 
paragraph -name 
PERFORM THRU st 



ERFORM routine 
me-exit, or PE 
A PERFORM 
can cause trou 
trying to main 
xample, if a p 
into two parag 
must examine e 
termine whethe 
is within the 
tement. Then 
rencing the 
must be change 
atements. 



-name 
RFORM 

ble for 

tain the 

aragraph 

raphs, 

very 

r or not 

range of 

all 

d to 



READ INTO and WRITE FROM Options 



Dse READ INTO and WRITE FROM, and do all 
processing in the Working-Storage Section. 
This is suggested for three reasons: 

1. Debugging is much simpler. 
Working-Storage areas are easier to 
locate in a dump than are buffer 
areas. And, if files are blocked, it 
is much easier to determine which 
record in a block was being processed 
when the abnormal termination 
occurred. 

2. Trying to access a record area after 
the AT END condition has occurred (for 
example, AT END MOVE HIGH-VALUE TO 
INPUT-RECORD) can cause problems if 
the record area is only in the File 
Section. 

3. WRITE FROM allows multiple writes of 
the same record (not possible when using 
the record area because of buffering 
techniques) . 

JSofe: The programmer should be aware that 
additional time is used to execute the move 
operation involved in each READ INTO or 
WRITE FROM instruction. 
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WRITE ADVA NCING with LINAGE, FOOTING,, and 
EMD-OF-PAGE 
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For ADVANCING nn LINES, COBOL first 
calculates the sura of LINAGE-COUNTER and 
nn. (For ADVANCING PAGE, see Case 2 
below.) Subsequent actions depend on the 
size of this value, as follows: 



Case J — If advance would be within the 

current logical page body (i.e., 
value is not greater than the 
established LINAGE value) : 

a. The WRITE takes place (either 
before or after advancing nn 
lines, as specified in the 
program) . 

b. LINAGE-COUNTER is incremented 
by nn. 

c. If FOOTING was speciifed, and 
the advance falls within the 
footing area (that is, greater 
than or equal to the 
established FOOTING value), the 
END-OF-PAGE imperative is 
executed (if one was 
specified) . 

Ca se 2 — If advance would go beyond the 

current logical page body (i.e., 
value is greater than the 
established LINAGE value) : 

a. A new value is established for 
LINES- AT -TOP. 

b. The WRITE takes place before or 
after (as specified by the 
program) the device is 
positioned to the first line of 
the next logical page. 

C. LINAGE-COUNTER is set to 1. 

d. New values are established fc 
LINAGE, FOOTING, and 
LINES-AT-BOTTOM. 



e. The END-OF-PAGE imperative is 
executed (if one was 
specified) . 

Note ; Files using LINAGE are treated 

as if the ADV compile option had been specified, 



MJTE_BEFJ)jlE/AFTJR_ADVANCING 

When the ADVANCING option is used for 
the WRITE statement, library subroutine 
ILBOSPA is called to handle the spacing. 
The carriage control characters are 
determined as follows : 

• When only AFTER is specified for the 
file, ASA control characters are 
used. 

• When only BEFORE is specified for the 
file, machine control characters are 
used. 

• When both BEFORE and AFTER are 
specified for output operations, 
machine control characters are used. 



RECEIVE Statement 



The RECEIVE statement makes available to 
the COBOL program a message, a message 
segment, or part of a message or message 
segment, as well as information about that 
message from a queue maintained by the 
message control program (MCP) . The 
following example of the RECEIVE statement 
is taken from the sample COBOL 
communication program shown in Figure 160: 

RECEIVE CDNAME-IN HESSAGE INTO IDENT-REC. 



S END Sta tem ent 



Specification of the SEND statement in 
the COBOL program causes a message, a 
message segment, or part of a message or 
message segment to be released to the 
message control program (MCP) . The 
following example of the SEND statement is 
taken from the sample COBOL communication 
program shown in Figure 147: 

SEND CDNAHE-OUT FROM IDENT-SEND WITH EHI. 



gotes: 



Although the COBOL program has access 
to a message only when the HCP has 
received it in entirety and placed it 
in a queue, once several messages have 
met this requirement the COBOL program 
can process messages from different WCP 
queues at the same time. 
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If one execution of a RECEIVE statement 
(or a SEND statement) transmits only 
part of a message, subsequent 
executions of RECEIVE statements (or 
SEND statements) in that run unit are 
required for transmission of the rest 
of the message. 

The MCP does not transmit data until 
the COBOL program has sent it a complete 
message. This complete message is 
built in a buffer in the region in 
which the COBOL program is executing. 

iULS. A 1L1 _ Si a tements 



Me t h od_2 : 



START file-name USING KEY data-name 
( EQUAL TO] 

identifier 






[ INVALID KEY imperative- statement] 



where data-name is the data-name given in 
the RECORD KEY clause and identifier 
contains the generic key value for the 
request and may be any data item whose 
length is less than or equal to that of the 
RECORD KEY. 



These two verbs are used in a COBOL 
communication program to allow/inhibit data 
transfer. For output, this transfer is 
between specified output queues and output 
destinations; for input, transfer is 
between specified sources and input queues 
COBOL provides an interface between the 
program and the TCAM message control 
program (MCP), where enabling/disabling 
actually occurs. For more detail, see the 
section "Using the Communication Feature." 



jjgte: For ISAM a problem may result with 
the generic key facility with binary key if 
the low-order byte of the search arguaent 
is binary zero. 



STRING statement 



START Statement 



For a sequentially-accessed ISAM file, 
the START statement must be executed before 
the READ statement for a given record if 
either of the following is true: 

• Processing begins with other than the 
first record; 

• Processing continues with a record 
other than the next sequential record. 

There are two ways to use the START 
statement to begin processing a segment of 
a sequentially accessed ISAM file at a 
specified key. The programmer may indicate 
either Method 1, to begin at a specific 
NOMINAL KEY that matches a RECORD KEY 
within the file, or Method 2, to start 
within the first record in a specific 
generic key class. 

Method, 1 : 

START file-name 

f INVALID KEY imperative-statement] 



The STRING statement combines two or 
more subfields into a single field. When 
this statement is executed, characters from 
the sending item (s) are transferred to the 
receiving item in the same way that moves 
from alphanumeric to alphanumeric item <s) 
are effected. The example in Figure 110 
illustrates the use of the STRING statement 
options available to the user, For a 
discussion of the formats possible with the 
STRING statement, see the publication IBM 
IS_COBOL_f or_0S./VS . 



The TRANSFORM statement generates more 
efficient code than the EXAMINE statement 
with the REPLACING BY option when only one 
character is being transformed. TRANSFORM, 
however, uses a 256-byte table. 
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STRING SNDFLD5 DELIMITED BY DLMTR 
SNDFLD6 DELIMITED BY SIZE 

* Combine data in SNDFLD5 up to the delimiter indicated by DLMTR with all the data 

* in another sending field (as indicated by the SIZE option of the STRING 

* statement). 

INTO RCDFLD1 WITH POINTER POINTS 

* Place the result in RCDFLD1 beginning at the relative location designated 

* by POINTR. 

ON OVERFLOW GO TO OVERFLOW2. 

* If RCDFLD1 is not large enough to accommodate the combined data-fields, or 

* if the original contents of the pointer field sere less than 1, execute a user- 

* written checking routine called OVERFLOW2. 

Figure 110. Using the STRING Statement 
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UNSTRING SNDFLD 

* Separate the data in the sending area. 

DELIMITED BY DLMTR1 

OS SPACES 

OS ALL »E« 
INTO RCFLD 

* When the character, or set of characters, marking the end of a section of the 

* sending area is found, move the isolated data into the data-receiving field. 

DELIMITER IN DELIM-IN 

* Move the delimiter found into the delimiter-receiving area DELIM-IN. 

COUNT IN COUNT-IN 

* Specify in COUNT-IN the number of characters placed in the RCFLD 

* data-receiving field. 

WITH POINTER POUNTE 



* Indicate the relative position in the SNDFLD sending area of the first 

* character to be examined. At the end of the operation, POINTR contains a value 

* equal to the initial value plus the number of characters examined in the sending 

* field. 

TALLYING IN TALLY-IN 

* Record the number of data-receiving areas acted upon. At the end of the 

* operation, TALLY-IN will contain a value equal to the initial value plus the 

* number of receiving areas acted upon. 

ON OVERFLOW 

DISPLAY »OVEBFLOW CONDITION' 
GO TO CHECK-SOUTINE. 

* If the data-receiving fields cannot accommodate the data being sent, or if 

* the original value of the pointer was less than 1 or greater than the si-ze of the 

* sending field, execute a user-written checking routine. 

i 

Figure 111. Using the UNSTRING Statement 



UNSTRING Statement 



REPORT Clause in FD 



The UNSTRING statement separates 
contiguous data in a sending field, placing 
it in multiple receiving fields. The 
example in Figure 111 illustrates the use 
of the UNSTRING statement options available 
to the user. 



For a discussion of the formats possible 
with the UNSTRING statement, see the 
publication IBM VS COBOL for OS/VS. 



A given report-name may appear in a 
maximum of two file description entries. 
The file description entries need not have 
the same characteristics. If the same 
report-name is specified in two file 
description entries, the report will be 
written on both files. For example: 



ENVIRONMENT DIVISION. 

SELECT FILE-1 ASSIGN UR- 1 403- S-PRTOUT. 
SELECT FILE- 2 ASSIGN UT-24 00- S-SY SUT1 . 



USING THE REPORT WRITES FEATURE 



DATA DIVISION. 

FD FILE-1 RECORDING MODE F 

RECORD CONTAINS 121 CHA8ACTERS 
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REPORT IS REPORT- A. 
FD FILE-2 RECORDING MODE 7 

RECORD CONTAINS 101 CHARACTERS 
REPORT IS RE PORT- A. 



For each GENERATE statement, the records 
for REPORT-A will be written on FILE-1 and 
FILE-2, respectively. The records on 
FILE-2 will not contain columns 102 through 
12 1 of the corresponding records on FILE-1. 
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Unless each identifier is the name of a 
SUM counter in a TYPE CONTROL FOOTING 
report group at an equal or lower position 
in the control hierarchy, the identifier 
must be defined in the File, 
Working-Storage or Linkage Sections, as 
well as in a TYPE DETAIL report groap as a 
SOURCE item. A SUM counter is 
algebraically incremented just before 
presentation of the TYPE DETAIL report 
group in which the item being summed 
appears as a source item or the item being 
summed appeared in a SUM clause that 
contained an UPON option for this DETAIL 
report group. This is known as SOURCE-SUM 
correlat ion. In the following example, 
SUBTOTAL is incremented only when DETAIL- 1 
is generated: 

FILE SECTION. 



05 NO-PURCHASES 



PICTURE 99. 



REPORT SECTION. 

01 DETAIL-1 TYPE DETAIL. 

05 COLUMN 30 PICTURE 99 SOURCE 

NO-PURCHASES. 



RD... CONTROLS ARE YEAR MONTH WEEK DAYY 



Method 1 



01 DETAIL-2 TYPE DETAIL. 



01 TYPE CONTROL FOOTING YEAR. 

05 SUM COST. 
01 TYPE CONTROL FOOTING MONTH. 

05 SUM COST. 
01 TYPE CONTROL FOOTING WEEK. 

05 SUM COST. 
01 TYPE CONTROL FOOTING DAYY. 

05 SUM COST. 



01 DAY TYPE CONTROL FOOTING 
LINE PLUS 2. 



05 SUBTOTAL COLUMN 30 PICTURE 999 
SUM NO-PURCHASES. 



H£thod_2: 

01 TYPE CONTROL FOOTING YEAR. 

05 SUM A. 
01 TYPE CONTROL FOOTING MONTH. 

05 A SUM B. 
01 TYPE CONTROL FOOTING WEEK. 

05 B SUM C. 
01 TYPE CONTROL FOOTING DAYY. 

05 C SUM COST. 



Method 2 will execute faster. One addition 
will be performed for each day, one more 
for each week, and one for each month. In 
Method 1, four additions will be performed 
for each day. 



01 MONTH TYPE CONTROL FOOTING 
LINE PLUS 2 NEXT GROUP 
NEXT PAGE. 



SUM Ro utine s 



A SUM routine is generated by the Report 
Writer for each DETAIL report group of the 
report. The operands included for summing 
are determined as follows: 

1. The SUM operand (s) also appears in a 
SOURCE clause (s) for the DETAIL report 
group. 
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2. The UPON detail-name option was 

specified in the SUM clause. In this 
case, all the operands are included in 
the SUM routine for only that DETAIL 
report group, even if the operand 
appears in a SOURCE clause in other 
DETAIL report groups. 
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The following examples show the SUM 
routines that are generated by the Report 
Writer. Example 1 illustrates how operands 
are selected for inclusion in the routine 
on the basis of simple SOURCE-SUM 
correlation. Example 2 illustrates how 
operands are selected when the UPON 
detail-name option is specified. 



EXAMPLE 1 : The following statements are 
coded in the Report Section: 



01 DETAIL- 1 TYPE DE. 
05 ... SOURCE A. 



01 DETAIL- 2 TYPE DE. 
05 ... SOURCE B. 
5 ... SOURCE C. 



SUM Routine for DETAIL-2 

REPORT-SAVE 

ADD B TO SUM-CTR-1. 

ADD C TO SUM-CTR-1. 

ADD B TO SUM-CTR-2. 
REPORT- RETURN 

SUM Routine for DETAIL-3 

REPORT-SAVE 

ADD B TO SUM-CTR-1. 

ADD B TO SUM-CTR-2, 
REPORT- RETURN 



EXAMPLE _2: In this example, the same 
coding is used as in Example 1, with one 
exception: the UPON detail-name option is 
used for SUM-CTR-1, as follows: 

01 TYPE CF... 

05 SUM-CTR-1.. .SUM A, B, C UPON 
DETAIL-2. 

The following SUM routines would then be 
generated instead of those resulting from 
the calculations in Example 1. 

SUM Routine for DETAIL- 1 

REPORT-SAVE 
REPORT- RETURN 

SUM Routine for DETAIL-2 

REPORT-SAVE 

ADD A TO SUM-CTR-1. 

ADD B TO SUM-CTR-1. 

ADD C TO SUM-CTR-1. 

ADD B TO SUM-CTR-2. 
REPORT- RETURN 

SUA Routine for DETAIL-3 



01 DETAIL-3 TYPE DE. .. 
05 ... SOURCE B. 



REPORT-SAVE 

ADD B TO SUM-CTR-2, 
REPORT- RETURN 



01 TYPE CF... 

05 SUM-CTR-1... SUM A, B, C. 



01 TYPE CF... 

05 SUM-CTR-2. ..SUM B. 



One SUM routine is generated for each 
DETAIL report group, as follows: 

SUM Routine for DETAIL-1 



Qutput_._Lifl e Overlay 



The Report Writer output line is put 
together with an internal REDEFINES 
specification, indexed by integer- 1. No 
check is made to prevent overlay on any 
line. For example: 

05 COLUMN 10 PICTURE X{23) 

VALUE "MONTHLY SUPPLIES REPORT". 

05 COLUMN 12 PICTURE X{9) 

SOURCE CURRENT-MONTH. 



REPORT-SAVE 

ADD A TO SUM-CTR-1. 
REPORT-RETURN 



the length of 23 in column 10, followed by 
a specification for column 12 will cause 
field overlay. 
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Page^Breaks 



The Report Writer page break routine 
operates independently of the routines that 
are executed after any control breaks 
{except that a page break will occur as the 
result of a LINE NEXT PAGE clause) . Thus, 
the programmer should be aware of the 
following facts; 



1. 



2. 
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GROUP INDICATE items are printed after 
page and control breaks. Figure 112 
contains a GROUP INDICATE clause and 
shows the execution output. 



WITH CODE Clause 



i 

| REPORT SECTION 

J 

I 

J 

J01 

I 
I 
I 
1 
I 
1 
I 
J 
I 
i 
! 
I 
J — 



DETAIL-LINE TYPE IS DETAIL LINE 

NUMBER IS PLUS 1. 

05 COLUMN IS 2 GROUP INDICATE 
PICTURE IS A (9) SOURCE IS 
MONTHNAME OF RECORD-AREA (MONTH) 



(Execution output) 



J 

IJANUARY 15 A00.. 
J A02.. 

I 

| PURCHASES AND COST.. 

I 



IJANUARY 

I 



21 



A03. 
A03, 



Figure 112. Sample Showing GROUP INDICATE 
Clause and Resultant Execution 
Output 



i 1 i 

J J Control J 

J Code | Character J Record 

I 4 1 




When more than one report is being 
written on a file and the reports are to be 
selectively written, a unique 1-character 
code must be given for each report. A 
mnemonic- name is specified in the RD- level 
entry for each report and is associated 
with the code in the Special-Names 
paragraph of the Environment Division. 



Note: If a report is written with the CODE 
option, the report should not be written 
directly to a printer device. 



This code will be written as the first 
character of each record that is written on 
the file. When the programmer wishes to 
write a report from this file, he needs 
merely to read a record, check the first 
character for the desired code, and have it 
printed if this code is found. The record 
should be printed starting from the third 
character, as illustrated in Figure 113. 
should be printed starting from the second 
character for ADV, third character for NOADV, 
as illustrated in Figure 113. 



Figure 113. Format of a Report Record When 
the CODE Clause is Specified 



The following example shows how to 
create and print a report with a code of A. 
A Report Writer program contains the 
following statements: 
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ENVIRONBENT DIVISION. 



SPECIAL- NAMES. 



»A« IS CHR-A 
«B» IS CHR-B, 



DATA RECORD IS PRINT-REC. 
01 PRINT- SEC. 

05 FILLER PICTURE X(121) 



PROCEDURE DIVISION. 



DATA DIVISION. 

FILE SECTION. 

FD RPT-OUT-FILE 

RECORDS CONTAIN 122 CHARACTERS 
LABEL RECORDS ARE STANDARD 
REPORTS ARE REP-FILE-A REP-FILE- B. 



LOOP. READ RPT-IN-FILE AT END 
GO TO CONTINUE. 
IF CODE-CHR = "A" 
WRITE PRINT-REC FROM 

PRINT-PART 
AFTER POSITIONING CTL-CHR 

LINES. 
GO TO LOOP. 
CONTINUE. 



REPORT SECTION. 
RD REP-FILE-A 



CODE CHR-A. .. 



RD REP-FILE-B CODE CHR-B... 



Control Footings and Page F oraat 



The RPT-OUT-FILE must be written on a tape 
or mass storage device. A second program 
coald then be used to print only the report 
with the code of A, as follows: 

DATA DIVISION. 
FD RPT-IN-FILE 

RECORD CONTAINS 122 CHARACTERS 

LABEL RECORDS ARE STANDARD 

DATA RECORD IS RPT-RCD. 
01 RPT-RCD. 

05 CODE-CHR PICTURE X. 

05 PRINT-PART. 

10 CTL-CHR PICTURE X. 

10 RECORD-PART PICTURE X(120). 
FD PRINT-FILE 

RECORD CONTAINS 121 CHARACTERS 

LABEL RECORDS ARE STANDARD 



Depending on the number and size of 
Control Footings (as well as the page depth 
of the report) , all of the specified 
Control Footings may not be printed on the 
same page if a control break occurs for a 
high-level control. When a page condition 
is detected before all reguired Control 
Footings are printed, the Report writer 
will print the Page Footing (if specified) , 
skip to the next page, print the Page 
Heading (if specified), and then continue 
to print control Footings. 

If the programmer wishes all of his 
Control Footings to be printed on the same 
page, he must format his page in the 
RD-level entry for the report (by setting 
the LAST DETAIL integer to a sufficiently 
low line number) to allow for the necessary 
sp ace. 
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RD EXPENSE-REPORT CONTROLS ARE FINAL, 
MONTH, DAYY 



01 TYPE CONTROL FOOTING DAYY 
LINE PLUS 1 NEXT GROUP 
NEXT PAGE. 



and after printing, line-counter = 40, 
then this next BODY GROUP 

01 TYPE DETAIL LINE PLUS 5 

would be printed on line 12+1 (i.e., 
line 13). 



01 TYPE CONTROL FOOTING MONTH 
LINE PLUS 1 NEXT GROUP 
NEXT PAGE. 



(Execution Output) 
EXPENSE REPORT 



Report Writer Rout ines 



At the end of the analysis of a report 
description entry (RD) , the Report Writer 
routines are generated, based on the 
contents of the RD. Each routine refers to 
the compiler-generated card number of its 
own respective RD. 



January 31. ...29.30 

(Output for CF DAYY) 

January total 131.40 

(Output for CF MONTH) 



Note: The NEXT GROUP NEXT PAGE clause for 
the control footing DAY is not activated. 



Flo§^i,B2, £irst Detail Rule 



The first presentation of a body group 
(CH, CF, or DE) that contains a relative 
line as its first line. Mill have its 
relative line spacing suppressed, and the 
first line will be printed on either the 
value of FIRST DETAIL or INTEGER PLUS 1 of 
a NEXT GROUP clause from the preceding 
page. For example: 



A. If the following body group was the 
last to be printed on a page 



01 TYPE CF NEXT GROUP NEXT PAGE 

Then this next body group 

01 TYPE DE LINE PLUS 5 

would be printed on value of FIRST 
DETAIL (in PAGE clause). 

B. If the following body group was the 
last to be printed on a page 

01 TYPE CF NEXT GROUP LINE 12 



TABLE HANDLING CONSIDERATIONS 



Subscripts 



If a subscript is represented by a 
constant and if the subscripted item has a 
fixed length, the location of the 
subscripted data item within the table or 
list is resolved at compile time. 

If a subscript is represented by a 
data-name, the location is resolved at 
execution time. The most efficient format, 
in this case, is COMPUTATIONAL, with 
PICTURE size less than five integers. 

The value contained in a subscript is an 
integer that represents an occurrence 
number within a table. Every time a 
subscripted data-name is referred to in a 
program, the compiler generates up to 16 
instructions to calculate the correct 
displacement. Therefore, if a subscripted 
data-name is to be processed extensively, 
move the subscripted item to an 
unsubscripted work area, do all necessary 
processing, and then move the item back 
into the table. Even when subscripts are 
described as computational, subscripting 
takes time and main storage. 

There is, however, compiler optimization 
in the computation of displacements. If a 
subscripted data item is referred to more 
than once in the same paragraph, the 
displacement for the data item is computed 
only once, then saved and used again for 
the subseguent references. For example: 

MOVE ITEM (A, B) TO D. 
MOVE ITEH (A, B,) TO E. 

If these two statements occur in the same 
paragraph, and no statements between them 
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could change the values stored in A or B, 
then the location of ITEM (A, B) will be 
computed only once and saved, and used 
again for the second reference. 



clause. The table element must then be 
ordered upon the key (s) data-name (s) 
specified. 



Index- Names 



DEPENDING ON Option 



Index-names are compiler-generated 
items; one fullword in length, assigned 
storage in the TGT. An index-name is 
defined by the INDEXED BY clause. The 
value in an index-name represents an actual 
displacement from the beginning of the 
table that corresponds to an occurrence 
number in the table. Address calculation 
for a direct index takes a maximum of four 
instructions; address calculation for a 
relative index takes a few more. 
Therefore, the use of index-names in 
referencing tables is more efficient than 
the use of subscripts. The use of direct 
indexes is faster than the use of relative 
indexes. 

Index- names can only be referenced in 
the PERFORM, the SEARCH* and the SET 
statements. 



Index Data Itej 



Index data items are compiler-generated 
storage positions* one fullword in length* 
that are assigned storage within the COBOL 
program area. An index data item is 
defined by the OSAGE IS INDEX clause. The 
programmer can use index data items to save 
values of index-names for later reference. 



Great care must b 
values of index data 
data item is not par 
compiler places the 
index- name or other 
the index data item 
in "SET Statement"), 
only be referenced i 
statements, a relati 
USING phrase of a PE 
or ENTRY statement. 



OCCURS Clause 



e used when setting 

items. Since an index 
t of any table* the 
value contained in the 
index data item into 
(see the example given 
Index data items can 
n SEARCH and SET 
onal condition* or the 
OCEDURE DIVISION CALL 



A table, e lement is represented by the 
subject of an OCCURS clause, and is 
equivalent to one level of a table. If 
indexing is to be used to reference a table 
element, and the Format 2 {SEARCH ALL) 
statement is also to be used, the KEY 
option must be specified in the OCCURS 



If a data item described by an OCCURS 
clause with the DEPENDING ON data-name 
option 1 is followed by nonsubordinate data 
items, a change in the value of data - name 
during the course of program execution will 
have the following effects: 



1. 



The size of any group described by or 
containing the related OCCURS clause 
will reflect the new value of 
data-name . 

Whenever a MOVE to a field containing 
an OCCURS clause with the DEPENDING ON 
option is executed, the MOVE is made 
on the basis of the current contents 
of the object of the DEPENDING ON 
option. 



The location of any nonsu 
items following the item 
with the OCCURS clause wi 
affected by the new value 
data-name. If the user w 
preserve the contents of 
the following procedure c 
prior to the change in da 
all nonsubordinate items 
variable item to a work a 
the change in data-name, 
items back. 



bordinate 
described 
11 be 

of 
ishes to 
these items* 
an be used: 
t a- name, move 
following the 
rea; after 
move all the 



Note: The value of data-name may change 
because a move is made to it or to the 
group in which it is contained; or the 
value of data-name may change because the 
group in which it is contained is a record 
area that has been changed by execution of 
a READ statement. 

For example, assume that the Data 
Division of a program contains the 
following coding: 

01 ANYRECORD. 

05 A PICTURE S999 COMPUTATION AL-3. 
05 TABLEA PICTURE S999 OCCURS 1 TO 

100 TIMES DEPENDING ON A. 
05 GROUPB. 

(Subordinate data items.) 

(End of record.) 



*For a discussion of the use of the OCCURS 
DEPENDING ON clause in a sort program, see 
"Sorting Variable-Length Records," 
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GROUPB items are not subordinate to TABLEA, 
which is described by the OCCURS clause. 
Assuming that WOHKB is a work area with the 
same data structure as GRO0PB, the 
following procedural coding could be used: 

1. MOVE GBOOPB TO WORKB 

2. Calculate new value of A 

3. MOVE WORKB TO GSOUPB 

The above statements can be avoided by 
putting the OCCURS clause with the 
DEPENDING ON option at the end of the 
record. 

Sote: Data- name can also change because of 
a change in the value of an item that 
redefines it. In this case, the group size 
and the location of nonsubordinate items as 
described in the two preceding paragraphs 
cannot be determined. 



identifier, or an index-name from another 
table element, it is set to an actual 
displacement from the beginning of the 
table element that corresponds to the 
occurrence number indicated by the second 
operand in the SET statement. The compiler 
performs all the necessary calculations. 
If the SET statement is used to assign an 
index-name to another index-name for the 
same table element, the compiler need make 
no conversion of the actual displacement 
value contained in the second operand. 



However, wh 
to another ind 
index- name, or 
an index data 
to change any 
since an index 
table. Thus, 
take place. I 
this, programm 



en an index data item is set 
ex data item or to an 

when an index-name is set to 
item, the compiler is unable 
displacement value it finds, 

data item is not part of any 
no conversion of values can 
f the programmer forgets 
ing errors can occur. 



SET Statement 

The SET statement is used to assign 
values to index-names and to index data 
items. 

When the SET statement assigns to an 
index-name the value of a literal. 



B (1) 



B (2) 



C (1, 1) 



C (1 # 2) 



C (2. 1) 



C (2, 2) 



D (1, 1, 1) ] E 

\— 
,D <1„ 1, 2) | E 
J. 

,D (1, 1, 3) ] E 

1- 

D (1,„ 2„ 1) ] E 
L— 

D (1, 2, 2) ] E 

\ 

D (1* 2„ 3) ] E 

k— 

D (2* 1. 1) ] h 

r 

D <2 W l m 2) j E 

Y— 

D (2 W 1, 3) \ E 

k— 
D (2„ 2 W 1) ] E 

D (2. 2„ 2) ] E 

J~- " 
D (2, 2 m 3) ] E 
l 



"T — 

|F 

■+- 
|F 

-+- 
IF 

-+- 

)F 

-+" 
I* 

■+- 
|F 

-+" 
IF 

-+- 
IF 

-+- 
IF 

-+" 

IF 

-+„ 

IF 
-+- 

IF 
_x 



Byte 
No. 



25 

50 

75 

100 

125 

150 

17 5 

200 

225 

250 

275 

300 



Figure 114. Storage Layout for Table Reference Example 
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For example, suppose that a table has 
been defined as: 

01 A. 

02 B OCCURS 2 INDEXED BY 11, 15. 

03 C OCCURS 2 INDEXED BY 12, 16. 

04 D OCCURS 3 INDEXED BY 13, 14. 
05 E PIC X{20) . 
05 F PIC 9<5) . 

Figure 114 shows how the table is laid 
out in main storage. 

Now, suppose it is necessary to 
reference D (2,2,3). The following steps 
are incorrec t: 

SET 13 TO 2. 

SET INDX-DATA-ITM TO 13. 

SET 12, 11 TO INDX-DATA-ITM. 

SET 13 UP BY 1. 

MOVE D(I1, 12, 13) TO 80RKAREA. 



SET 13 TO 2. 

SET 12, 11 TO 13. 

SET 13 UP BY 1. 

In this case, the first SET statement 
places the value 25 in I 3. Since the 
compiler is able to calculate the lengths 
of B and C, the second SET statement places 
the value 75 in 12, and the value 150 in 
11. The third SET statement places the 
value 50 in 13. The correct address 
calculation will be: 

(address of D(1,1,1)) ♦ 150 ♦ 75 + 50 = 
(address of D( 1,1,1)) ♦ 275. 

The rules for the SET statement are 
shown in Figure. .1 15. 



SE ARCH Statement 



The value contained in 13 after the first 
SET statement is 25, which represents the 
beginning point (in bytes) of the second 
occurrence of D. When the second SET 
statement is executed, the value 25 is 
placed in INDX-DATA-ITM, and the third SET 
statement moves the value 25 into 12 and 
11. The fourth SET statement increases the 
value in 13 to 50. The calculation for the 
address D (11, 12, 13) would then be as 
follows: 



(address of D (1,1,1)) ♦ 25 ♦ 25 ♦ 50 = 
(address of D( 1,1,1)) ♦ 100 

where D( 1,1,1) represents the first 
occurrence of D. This is not the address 
of D (2,2,3). 

The following steps will find the 
correc t address: 



Only one level of a table (a table 
element) can be referenced with one SEARCH 
statement. Note that SEARCH statements 
cannot be nested, since an 
imperative- statement must follow the WHEN 
condition, and the SEARCH statement is 
itself conditional. 

There are two formats for the SEARCH 
statement. 

Format 1 SEARCH statements perform a 
serial search of a table element. If the 
programmer knows that the "found" condition 
will come after some intermediate point in 
the table element, to speed up execution, 
he can use the SET statement to set the 
index-names at that point and search only 
part of the table element. If the table 
element is large, and must be searched from 
the first occurrence to the last, the use 
of Format 2 (SEARCH ALL) is more efficient 



! T" 

Sending! 




! Index-name 



Index Data Item 



Identifier 
or Literal 



Set to value 
corresponding 
to occurrence 
number *- 



Move without 
conversion 



Set to value 
corresponding 
to occurrence 
number 



Move without 
conversion 



Move without 
conversion 



Set to occurrence J 
number represented | 
by index-name j 
x. 



j *-If index-name refer to the same table element move without conversion 



Figure 115. Rules for the SET Statement 
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than Format 1, since it uses a binary 
search technique; however, the table oust 
then be ordered. 

In Format 1, the VARYING option allows 
the programmer to: 

• Vary an index-name other than the first 
index- name stated for this table 
element. Thus, with two SEARCH 
statements each using a different 
index- name, reference can be made to 
more than one value in the same table 
element for comparisons, etc. 

• Vary an index-name from another table 
element. In this case, the first 
index-name specified for this table 
element is used for the search, and the 
index-name specified in the VARYING 
option is incremented at the same time. 
Thus, it is possible to step through 
two table elements at once. 



In Form 
any relati 
multiple. 
stated, th 
OB -- that 
conditions 
imperative 
condition 
of the SEA 
before exi 
WHEN condi 
connective 



at 1, the WHEN 
on condition, 

If multiple W 
e implied logi 

is, if any on 

is satisfied, 
-statement fol 
is executed. 
RCH statement 
ting from the 
tion with an A 

must be writt 



condition can be 
and can be 
HEN conditions are 
cal connective is 
e of the WHEN 

the 
lowing the WHEN 
If lil conditions 
are to be satisfied 
search, a compound 
ND logical 
en. 



05 B OCCURS 2 INDEXED BY 11 15. 

10 C OCCDRS 2 INDEXED BY 12 16. 

15 D OCCURS 3 INDEXED BY 13, 14. 
20 E PIC X(5). 
20 F PIC 9(5) . 



(initialize comparandl and comparand2) 



PERFORM SEARCH-TEST1 THRO SEARCH-EXIT1 
VARYING 11 FROM 1 BY 1 UNTIL 11 GREATER 
THAN 2 AFTER 12 FROM 1 BY 1 UNTIL 12 
GREATER THAN 2. 
ENTRY-NOENTRY1. GO TO ERROR-RECOVERY 1 . 



SEARCH-TEST1. SET 13 TO 1. 

SEARCH D WHEN E (11, 12, 13) = 

C0MPARAND1 AND 

F (11, 12, 13) = COMPAFAND2 

SET 15 TO 11 

SET 16 TO 12 

SET 12 TO 3 

SET 11 TO 3 

ALTER ENTRY-NOENTRY1 TO PROCEED TO 

ENT8Y-PROCESSING1. 
SEARCH-EXIT 1. EXIT. 



ERROR-RECOVERY 1. 



In Format 2, the SEARCH ALL statement, 
the table must be ordered on the KEY(S) 
specified in the OCCURS clause. Any KEY 
may be specified in the WHEN condition, but 
all preceding data-names in the KEY option 
must also be tested. The test must be an 
"equal to" (=) condition, and the KEY 
data-name must be either the subject of the 
condition or the name of a conditional 
variable with which the tested condition- 
name is associated. The WHEN condition can 
also be a compound condition, formed from 
one of the simple conditions listed above, 
with AND as the only logical connective. 
The KEY and its object of comparison must 
be compatible, as given in the rules of 
the relation test. 

To write a series of statements that 
will search the three-dimensional table 
discussed in the section "The SET 
Statement," the programmer could write: 

77 COMPARAND1 PIC X(5). 
77 C0MPARAND2 PIC 9(5). 
01 A. 



ENTRY-PROCESSING 1. 

MOVE E(I5, 16, 13) TO OUT-AREA1. 
MOVE F(I5, 16, 13) TO OUT-AREA2, 



The PERFORM statement varies the indexed 
(II and 12) associated with table elements 
B and C; the SEARCH statement varies 13, 
which is associated with table element D. 

The values of 1 1 and 12 that satisfy the 
WHEN conditions of the SEARCH statement are 
saved in 15 and 16. 11 and 12 are then 
both set to 3 using the SET statement, so 
that upon return from the SEARCH statement 
control will fall through the PERFORM 
statement to the GO TO statement. 

Subsequent references to the desired 
occurrence of table elements E and F make 
use of the index-names 15 and 16 in which 
the correct value was saved. 
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10 


PART-1 


10 


KEY-1 


10 


PART- 2 


10 


KEY-2 


10 


PART-3 


10 


KEY-3 



For example, a user-defined table may be 
the following: 

01 TABLEA. 

05 ENTRY-IN-TABLEE OCCURS 90 TIHES 
ASCENDING KEY-1, KEY-2 
DESCENDING KEY-3 
INDEXED BY INDEX-1. 

PICTURE 9 (2) . 

PICTURE 9 (5). 

PICTURE 9(6) . 

PICTURE 9 (U) . 

PICTURE 9(33) . 

PICTURE 9(5) . 



A search of the entire table can be 
initiated with the following instruction; 



SEARCH ALL ENTRY-IN-TABLEE AT 

END GO TO NOENTRY 
WHEN KEY-1 (INDEX-1) = VALUE-1 AND 

KEY-2 (INDEX-1) = VALUE-2 

AND KEY-3 (INDEX-1) = VALUE-3 
MOVE PART-1 (INDEX-1) TO 

OUTPUT-AREA. 



Buil ding Tables 



When reading in data to build an 
internal table: 

1. Check to make sure the data does not 
exceed the space allocated for the 
table. 

2. If the data must be in sequence, check 
the sequence. 

3. If the data contains the subscript 
determining its position in the table, 
check the subscript for a valid range. 



When testing for the end of a table, use 
a named value giving the itero count, rather 
than using a literal. Then, if the table 
must be expanded, only one value need be 
changed, instead of all references to a 
literal. 



QUEUE STRUCTURE CONSIDERATIONS 



The foregoing instructions will execute 
a search on the given array TABLEA which 
contains 90 elements of 55 bytes and 3 
keys. The primary and secondary keys 
(KEY-1 and KEY-2) are in ascending order 
whereas the least significant key (KEY-3) 
is in descending order. If an entry is 
found in which three keys are equal to the 
given values (i.e., VALUE-1, VALUE-2 
VALUE-3) PART-1 of that entry will be moved 
to OUTPUT-AREA, if matching keys are not 
found in any of the entries in TABLEA, the 
NOENTRY routine is entered. 



If a match is found between a table 
entry and the given values, the index 
(INDEX-1) is set to a value corresponding 
to the relative position within the table 
of the matching entry. If no match is 
found, the index remains at the setting it 
had when execution of the SEARCH ALL 
statement began. 



Compilation is faster if KEY(S) are 
tested in the SEARCH statement in the same 
order they appear in the KEY option. 



Note that if KEY entries within the 
table do not contain valid values, then the 
results of the binary search will be 
unpredictable. 



In a COBOL teleprocessing (TP) program, 
a CD FOR INPUT allows the specification of 
one through three levels of sub-queues from 
which data can be received; this allows the 
COBOL object program, at execution time, to 
make use of pre-defined queue structures, 
and to access all or parts of such 
structures. For TP programs, such queue 
structures are analogous in function and 
form to the File Description (FD) entry and 
its associated 01 record description for 
file processing programs. If pre-defined 
queue structures are used, each lowest 
level sub-queue name in the structure 
corresponds to a DD name; the associated DD 
card must specify a TPROCESS entry in the 
message control program (MCP) terminal 
table). Figure 116 shows the configuration 
of one queue structure such that gueue A is 
made up of sub-queues B and C, sub-queue B 
is made up of sub-queues D and E, and 
sub-queue D is made up of sub-queues H and 
I (where sub-queue H contains messages Z1 
and X2 and sub-queue I contains messages 
X3, X4, and X5) , and so on. 

During program execution, when the user 
wishes to receive a message from a queue 
(or sub-queue) he need not place the names 
of all sub-queues in the input CD; he need 
specify only the SYMBOLIC QUEUE name, which 
may be the name of a pre-defined queue 
structure, or he may specify that name plus 
one or more sub-queue names — which allows 
him to access only that part of the entire 
structure that is needed. A COBOL 
object-time subroutine uses the name(s) 
placed in the input CD to determine which 
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lowest-level sub-queue (s) and corresponding 
TCAM queue (s) can be used to fill the 
request. 



In order to do this, 
previously defined his q 
a form tffat is acceptabl 
object-time subroutine, 
that functions as the Qu 
Description routine (inc 
COBOL library) makes thi 
to the Queue Structure D 
consists of a series of 
define queue structures, 
are written in a COBOL-1 
to an PD entry and its a 
description entry. The 
Description routine prod 



the user must have 
ueue structures in 
e to the COBOL 

A utility program 
eue structure 
luded in the OS/VS 
s possible. Input 
escription routine 
statements that 

The statements 
ike format, similar 
ssociated record 
Queue Structure 
uces as output a 



partitioned data set with one member for 
each complete queue structure. The sample 
listing shown in Figure 117 provides the 
queue definition statements that correspond 
to the queue structure. At the right of 
each statement, in parenthesis, is each FD 
entry equivalent. 



Each logical record in a queue structure 
description may include only a queue or 
sub-queue definition; it may not include, 
for example, the usual COBOL sequence 
number. (For a detailed description of the 
possible formats for input to the Queue 
Structure Description routine, see the 
Section "Hules for Queue Structure 
Description" in this chapter.) 



QUEUE 



SUB- QUEUE (1) 



C| 



SUB- QUEUE (2) 



SUB- QUEUE (3) 



MESSAGE 



J. , 



EJ 



P X , 






Zl 


X3 


XI 


Z6 


Y7 


Yl 


X2 


X4 


Y3 


Z7 


Y8 


Y2 




X5 


Y5 
Z5 


Y6 










X6 



Z2 
Z3 

M 
Y4 



Figure 116. A Queue Structure with Three Levels of Sub-Queues 
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# 7 

J//BLDRDS JOB user inf or nation J 
I//JOBLIB* DD DSN=SYS1.COBLIB,UNIT=231U,VOL=SER=DC160,DISP=OLD 1 
I//SUBQS* EXEC PGM=ILBOQSU0,REGION=96K | 
I//C0BTPQD3 DD DSN=SUBQPDS, UNIT=23 1 <*, VOL=SER=DC 160, X \ 
I// SPACE=(4000, (50,20,1)) ,DISP= (OLD, KEEP) j 
I//SYSPRINT* DD STSO0T=A } 
I//SYSIH5 DD * | 

1// 1 


J QUEUE STRUCTURE DEFINITIONS FOR USE IN COBOL PRGGRAflS WHICH PROCESS QUEUES AND | 
| SUB-QUEUES- | 




Note: The parenthetical entries below are | 
for illustrative purposes only, they may J 
not appear in the program itself. \ 


| QUEUE IS A. 


(FD clause) | 


J SUB-QUEUE-1 IS B. 


(01 entry) J 


| SUB-QUEUE-2 IS D. 


(02 entry) j 


| SUB-QUEUE-3 IS H. 


(03 entry) \ 


J SUB-QUEUE-3 IS I. 


(03 entry) [ 


| SUB-QUEUE-2 IS B. 


(02 entry) | 


\ SUB-QUEUE-3 IS J. 


(03 entry) } 


i SUB-QUEUE-3 IS K. 


(0 3 entry) J 


J SUB-QUEUE-1 IS C. 


(01 entry) J 


J SUB-QUEUE-2 IS F. 


(02 entry) j 


| SUB-QUEUE-3 IS L. 


(03 entry) j 


I SUB-QUE0E-3 IS M. 


(0 3 entry) J 


| SUB-QUEUE-2 IS G. 


(02 entry) J 


| SUB-QUEUE-3 IS N. 


(0 3 entry) J 


| SUB-QUEUE-3 IS 0. 

t ,.. ,. j 


03 entry) J 

_, ., ,, i 


I J 
| N.o t es : 




|1. The data-set name SIS 1.COBLIB represents the OS/VS COBOL Library. i 


J2. The utility program ILBOQSU0 (called the Queue structure Description routine) } 
| creates a partitioned data set with one member for each complete queue structure J 
| defined. It has an alias name of BLDQS, which nay be specified on the EXEC card | 
J instead. J 


|3. The partitioned data set must be descril 


aed on a DD card with the reserved name J 


1 //COBTPQD . 




|4. The SYSPRINT DD statement defines the output message and listing data set. J 


|5. The SYSIN DD statement defines the input 
j consist of 80-character records. 


t to the program. The SYSIN data set must J 



Figure 117. A Sample Queue Structure Descripion 
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ACCESSING QUEUE STRUCTURES THROUGH COBOL 



Once the user has def 
queue structures, COBOL 
utilize these structures 
time, the partitioned da 
on a DD card with the v na 
for example, the user va 
messages described in t'h 
defined in Figure 117, a 
the partitioned data set 
would be required. 



ined and stored the 
TP programs can 
At execution 
ta set is described 
me COBTPQD. If, 
nted to access 
e queue structure 
DD card specifying 
SDBQPDS, as below, 



//COBTPQD DD DSN=SUBQPDS,DISP=SHR, 
UNIT=33 50,VOL=SER=DC160 



Additiona 
link the mes 
table entrie 
sub-queue na 
terminal tab 
"Terminal an 
chapter "Usi 
Feature".) 
defined eith 
(for example 
or as a ddna 
lowest- level 
alternative 
program to r 
without ambi 
are illustra 



1 DD cards w 
sage control 
s and the lo 
mes. {For a 
le entries, 
d Line Contr 
ng the Telep 
The name of 
er as the su 
, asH, I, J 
me that is e 
sub-queue n 
approach per 
euse SYHBOLI 
guity. Thes 
ted below. 



ould be required to 

program terminal 
west-level 

description of 
see the section 
ol Areas" in the 
rocessing 

the DD card may be 
b-gueue name itself 
, K, L, M, N, or 0) 
quivalent to the 
ame. This 
mits the COBOL 
C SUB-QUEUE names 
e two approaches 



Methp_d_jL: The DD card associated with the 
queue definition SUB-QUEUE-3 IS H would be: 

//H DD QNAME=Q1 

aethod 2: The DD card associated with the 
queue definition SUB-QUEUE-3 IS H(FISSTMSG) 
would be: 

//FIRSTMSG DD QNAME=Q1 

where Q1 is an entry in the terminal table. 

Before a RECEIVE statement is executed, 
the user places (via a HOVE statement) the 
needed queue and sub-queue name{s) in the 
CD entry. When the RECEIVE statement is 
executed, the RECEIVE subroutine checks for 
the presence of the partitioned data set 
describing these queue structures. If the 
data set is present, the RECEIVE subroutine 
invokes a Queue Analyzer routine, which 
searches the partitioned data set for a 
member corresponding to the name in the 
SYMBOLIC QUEUE field, reads that member 
into main storage, and uses it to validate 
the SYMBOLIC SUB-QUEUE name(s) in the COBOL 
program input CD entry. The Queue Analyzer 



routine then determines the first valid 
name for the structure specified and gives 
this name to the RECEIVE routine. 

Names at the SUB-QUEUE- 1 level take 
priority over names at the SUB-QUEUE-2 
level. Names at the SOB-QUEUE-2 level take 
priority over names at the SUB-QUEUE-3 
level. At any given level, names at the 
left take priority over, and are completely 
evaluated before, names at the right. 
(Taking advantage of this retrieval 
technique, the user can improve object- time 
performance by defining the most frequently 
used sub-queues at the left of the 
structure.) Figure 118 illustrates this 
process. 

The RECEIVE subroutine then attempts to 
access the queue specified. If there are 
no messages in the associated MCP queue, 
the Queue Analyzer provides the RECEIVE 
routine with another valid name. The 
procedure is repeated until the RECEIVE 
routine accesses a message, or until there 
are no more queues to access. 

During a RECEIVE operation, a COBOL 
program using queue structures need not 
specify all levels of sub-queues. The 
highest level (QUEUE) must be specified; 
that level plus a SUB-QUEUE- 1 may also be 
specified; or all four levels may be 
specified. If a lower level is specified, 
then all higher levels must also be 
specified. 

If the COBOL programmer wishes to access 
the next message in the queue structure, 
regardless of which sub-queue that message 
may be in, he specifies the queue name 
only, and initializes the sub-queue-names 
to SPACES. The Queue Analyzer, when 
supplying the message, returns to the COBOL 
object program any applicable sub-queue 
names via the data items in the associated 
input CD. In this way, if the entire 
message was not returned as a result of the 
current RECEIVE, additional RECEIVE 
requests may be issued using the complete 
queue and subqueue names in the CD to 
retrieve the balance of the message. If, 
however, the programmer wishes the next 
message in a given sub-queue, he must 
specify both the queue name and any 
applicable sub-queue names. Figure 118 
illustrates the relationship between the 
information contained in the input CD at 
object time and the message (s) accessed 
when the RECEIVE statement is executed 
(where each example refers to the queue 
structure pictured in Figure 116). 
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Input CD 



Message Returned by the MCP 



CD CDNAME-IN FOB INPUT 

SYMBOLIC QUEUE IS data-name-1. 
(where data-name- 1 contains "A*) 

CD CDNAHE-IN FOR INPUT 

SYMBOLIC QUEUE IS data-name-1. 

SYMBOLIC SUB-QUEUE- 1 IS data-name-2. 
(where data-name-1 contains 'A* and 
data-name-2 contains ' C) 

CD CDNAME-IN FOR INPUT 

SYMBOLIC-QUEUE IS data-name-1, 
SYMBOLIC-QUEUE-1 IS data-name-2, 
SYMBOLIC- QUEUE- 2 IS data-name-3. 
(where data-name- 1 contains 'A 1 , 
data-name-2 contains ' B*, 
and data-name-3 contains ' E 1 ) 



Message Z1 



Message Y7 



Message X1 



Note: Data-name-1, data-name-2, and so on, refer to the optional clauses of a queue 
structure defined under "Rules for Queue Structure Description" in this chapter. 
« 

Figure 118- Sample Message Retrieval Options 



Spec ifyi ng ddna^es with Elementary 
Su b- Que ues 



Suppose that an application program is 
written to accept TP messages as input to 
an inventory control process. Each of five 
different locations transmits data on four 
different parts. The diagram in Figure 119 
illustrates the relationship between the 
input messages and the four different parts 
for each location. 
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lowest level when he defines the structure 
to the Queue Structure Description routine. 
Then the object-time Queue Analyzer routine 
automatically associates the fully 
qualified queue structure names with the DD 
names required. Accordingly, in this 
example: 



NEW- YORK. PARTA could have ddname DDL 

NEW-YORK. PARTB could have ddname DD2. 

NEW-YORK. PARTC could have ddname DD3. 

NEW-YORK. PARTD could have ddname DD4. 

CHICAGO. PARTA could have ddname DD5. 

CHICAGO. PARTB could have ddname DD6. 

and so forth. In this way, each elementary 
queue has a unique designation; yet the 
COBOL program can refer to the sub-queue 
names without ambiguity. 
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SUB-QUEUE-2 
PAETA(DDI) 



SUB-QUEUE- 1 



QUEUE 



PAETB(DD2) — 
PARTC{DD3) — 
PABTD(DD4) — 



PASTA (DD5) 
PABTB{DD6) 
PABTC(DD7) 
PARTD<DD8) 

PAETA (DD9) 
PAETB(DD10 
PARTC{DD11 
PAETD(DD12 

PARTA{DD13 
PABTB(DD14 
PAETC(DD15 
PARTD{DD16 

PARTA(DD17 
PAETB{DD18 
PARTC(DD19 
PARTD(DD20 



-H 



-H 



NEW-YORK 



CHICAGO | 


ST-LOUIS \ INVENTORY 


DENVEB | 


1 

LOS- ANGELES J 



Figure 119. Using ddnaraes aith Queue structures 
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[[ 



QUEUE 

Q 

SUB-QUEUE- 1 
SUBQ1 

SUB-QUEUE- 2 
SUBQ2 

SUB-QUEUE- 3 
SUBQ3 



IS data 



IS data-name- 2 [ (ddname-) ] }.. 



IS data-;name-3 [(ddname) ]] -« 



IS data-name-4 [ (ddname-3) ]]...]}». 



Figure 120. Format for Input to Queue Structure Description Routine 



Rules for Queue St ructure Description 



For each member of the partitioned data 
set, the input to the Queue Structure 
Description Routine must take the format 
shown in Figure 120. 

The clauses of the gueue structure may 
be written free form; however, only one 
clause may appear on each 80-character 
record. At least one sub-gueue level must 
be specified; no more than 200 sub-gueue 
names may be specified in one gueue 
structure. 

The sub-gueues at each level must be 
specified to the Queue Structure 
Description routine in left-to-right order. 
When the gueue structure is referred to at 
object program execution time, names at a 
higher level take priority over names at a 
lower level. At a given level in the gueue 
structure, names to the left take priority 
over names to the right. 

A gueue structure need not include all 
levels of sub-gueues. However, if a lower 
level is included in one leg of a gueue 



structure, then that leg must include all 
higher levels. 



Each clause of the structure may 
optionally be followed by a period. 



D ata-na m e-1 is the name of the gueue 
structure, and becomes the name of that 
member of the partitioned data set. 

Data-name-2 though data- name-q are 
sub-gueue names within the data set member. 



I2£e: a data-name cannot contain more than 
12 characters. 

Each dat a-nam e at the lowest 
(elementary) level of a leg of the gueue 
structure may be a ddname; alternatively, 
each such data-name may be followed by a 
parenthesized ddname. If a parenthesized 
ddname follows a sub-gueue name, the left 
parenthesis must immediately follow the 
sub-gueue name with no intervening spaces. 
There must be no spaces between the 
parentheses and the ddname. 
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CALLING AND CALLED PROGRAMS 



A COBOL program can refer to and pass 
control to other COBOL programs, or to 
programs written in other languages. A 
program in another language can refer to 
and pass control to a COBOL program, A 
program that refers to another program is a 
ca llin g program- A program that is 
referred to is a call ed program. Control 
is returned from a called program to the 
first instruction following the calling 
seguence in the calling program. 



A called program can also be a calling 
program; that is, a called program can, in 
turn, call another program. However, a 
called program cannot call the program that 
called it, an earlier calling program, or 
itself. In Figure 121, for instance, 
program A calls program B; program B calls 
program C. Therefore: 

1 . A is considered a calling program by B. 

2. B is considered a called program by A. 

3. B is considered a calling program by C. 

4. C is considered a called program by B. 



Usually called and calling programs to 
be executed as a single job step are 
link-edited together; they must all be 
included in the same load module. However, 
with the COBOL dynamic call feature a 
programmer can request that a called 
program be link-edited into a separate 
module and called only if it is needed (see 
the section "Dynamic Subprogram Linkage", 
in this chapter) . 

This chapter describes the accepted 
linkage conventions for calling and called 
programs in both COBOL and assembler 
language and discusses how such programs 
are link-edited. An example is provided to 
illustrate the coding required to have 
proper interface between both COBOL and 
assembler language calling and called 
programs. In addition, it includes a 
discussion of overlay design in which 
different called programs may, at different 
times, occupy the same area in main 
storage. Another example is provided to 
illustrate one method of accomplishing 
program linkage using the dynamic overlay 
technique. 



SPECIFYING LINKAGE 



Control is returned in the same order of 
calling; that is, a called program {program 
C) returns control to its own calling 
program {program B) , not to an earlier 
calling program (program A). Compiler- 
generated switches {e.g., ON and ALTEB) are 
not reinitialized upon each entrance to the 
called program, that is, the program is in 
the last executed state unless it has been 
the object of a CANCEL statement. 



Whenever a program calls another 
program, a link must be established between 
the two. The calling program must state 
the entry point of the called program and 
must specify any identifiers to be passed. 
The called program must have an entry point 
and must be able to accept the identifiers. 
In addition, the called program must 
establish the linkage for the return of 
control to the calling program. See Figure 
122 for an example of the linkage 
statements required in a typical 
calling/called situation. 
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Figure 121. Calling and Called Programs 
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LINKAGE IN A CALLING COBOL PROGRAM 



LINKAGE IN A CALLED COBOL PROGRAM 



A calling COBOL program must contain the 
following statement at the point at which 
another program is to be called: 



CALL 



(literal-1 
(identif ier-1 



[USING identifier-list] 

[ON OVERFLOW imperative-statement]. 



A called COBOL program must contain two 
statements. 



One of the following statements must 
inserted to name the point where the 
program is to be entered: 



ENTBY literal-1 

[USING identifier-list], 

or 



be 
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If the called program is an 
assembler- language program, the identifier 
in the USING phrase may also be a file-name 
or a procedure- name. If the identifier in 
the USING phrase is a file-name, the COBOL 
compiler passes the address of the DCB for 
a queued file, or the address of the DECB 
for a basic file, as this entry of the 
identifier-list. The identifier may not be 
a VSAM file name. This can be used to test 
bits in the DCB or DECB or to enter some 
options in the DCB. However, when changing 
a field of the DCB, precautions should be 
taken not to contradict the information in 
other fields or the information in the 
object code supplied by the compiler, job 
control language, or other sources. When 
the identifier in the USING phrase is a 
procedure-name, the value passed is the 
beginning address of the procedure. If no 
identifiers are passed, the USING clause is 
omitted. 

If a non-standard return is executed to 
a procedure name in a program compiled with 
OPT, RES, or DYN options, unpredictable 
results may occur. 
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PROCEDURE DIVISION [USING 
identif ier- list ]. 

The literal-1 or PROGRAM-ID is the name of 
the entry point in the called program. If 
is the same name that appears in the CALL 
statement of the program that calls this 
program that the compiler uses. The 
identifier-list is one or more data-names 
that correspond to the identif ier- list of 
the CALL statement of the calling program, 
Each data name of the identifier-list must 
be defined in the Linkage Section of the 
Data Division and must have a level number 
of 01 or 77. 

One of the following statements must be 
inserted at the point at which control is 
to be returned to the calling program: 

GOBACK. 

or 

EXIT PROGRAM. 



The GOBACK or EXIT PROGRAM statement 
enables restoration of necessary registers 
and returns control to the point in the 
calling program immediately following the 
calling seguence. 



Note: The GOBACK and EXIT PROGRAM 
statements may be used in a main program, 
with the result that any COBOL program can 
be used as either a calling or a called 
program, if written with this end in mind. 
If a GOBACK statement appears within the 
main program, control is returned 
immediately to the system; if an EXIT 
PROGRAM statement appears, it is simply 
regarded as a null instruction. 

A called program may pass a completion 
code to its caller by storing a value in 
RETURN-CODE. The calling program may 
interrogate RETURN-CODE after a return is 
made from a called program to determine the 
completion code. 
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Note: EETU8N-C0DE iay also be used to pass 
a completion code to the system at the end 
of a run unit. 



Dyna mic Subprogram Linkage 



With the dynamic subprogram linkage 
feature, a called program need not be 
link-edited with the main program. It may 
instead be link-edited into a separate load 
module, so that at execution time it is 
loaded if and only if it is called. 
Accordingly, the first dynamic call to a 
subprogram obtains a fresh copy of the 
subprogram, subsequent calls to the same 
subprogram, by either the original caller 
or any other subprogram in the same 
region/partition, result in a branch to the 
same copy of the subprogram in its 
last-used state until the subprogram is 
canceled. The first call following a 
CANCEL statement results in a branch to a 
fresh copy of the subprogram. 

Specification of the DYNAM option in the 
PARM field of the EXEC statement (see the 
section on "Compiler Options" in the 
chapter entitled "Job Control Procedures") 
makes all calls dynamic. If NODYNAM is in 
effect, through either user specification 
at compile time or as the default option* 



only CALL identifier statements are 
dynamic; when NODYNAM is in effect, CALL 
literal statements are static. (For a 
discussion of the formats possible with the 
CALL statement, see the publication IB M , VS 
COBOL_ fo r_ OS/V S . ) 

For an example of a COBOL program that 
takes advantage of the dynamic CALL/CANCEL 
feature, see Figure 122. 



Note s: 

1. When the dynamic CALL 
main program and all 
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advantage of the COBO 
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The USING option should be included in 
the CALL statement only if there is a 
OSING option in the called entry 
point. 

It is recommended that calling 
programs use the ON OVEHFLOW facility. 
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//CALL JOB 

//STEP1 

//COB.SYSIN 



user information 

COBUCL,PARM.COB=»DYN AM RESIDENT* 



JOB 

EXEC 

DD * 

IDENTIFICATION DIVISION 

PROGRAM-ID. SUBPROG1. 

AUTHOR. J. SMITH 

REMARKS. 

THIS SUBPROGRAM IS CALLED BY THE MAIN PROGRAM. 

IT ISSUES A MESSAGE TO INDICATE WHETHER IT IS 

IN INITIAL OR LAST-USED STATE, AND THEN RETURNS 

TO THE MAIN PROGRAM. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370. 
DATA DIVISION. 
WORKING- STORAGE SECTION. 
77 SWITCH PIC 9 VALUE 0. 
PROCEDURE DIVISION. 

IF SWITCH=0 DISPLAY »SUBPR0G1 CALLED — IN 
INITIAL STATE* 

GO TO RETURN-POINT. 

DISPLAY •SUPROG1 CALLED — IN LAST-USED STATE 1 . 
RETURN-POINT. 

ADD 1 TO SWITCH. 

EXIT PROGRAM. 

/* 

//LKED.SYSLMOD DD DSN=SUBPROGS (SUBPROG1) ,UNIT=23 14, VOL=SER=XXXXXX, 

// DISP= (NEW, KEEP) , SPACE={TRK, (5,1,1)) 

/* 



Note; When a subprogram is called dynamically, the (NAME and/or ALIAS) option of the 
.linkage editor is used to identify the module that is accessed by an OS/VS LOAD macro 
Jat execution time (see the section entitled "Link-editing COBOL Programs"). 

i , , 

Figure 122. Sample Calling and Called Programs Using Dynamic CALL and CANCEL Statements 
(Part 1 of 3) 
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I//CALLJ0B2 
//STEP1 
I //COB. SYS IN 



JOB user information 

EXEC COBUCL,PARM.COB=»DYNAM, RESIDENT* 

J)D * 

IDENTIFICATION DIVISION. 

PROGRAM- ID. S0BP10G2- 

ADTHOR. J. SHITH 

REMARKS. 

THIS SUBPROGRAM IS CALLED BY THE MAIN PROGRAM. 

IF IT IS IN INITIAL STATE, IT ISSUES A MESSAGE 

TO THAT EFFECT AND RETURNS TO THE MAIN PROGRAM. 

IF NOT, IT ISSUES A MESSAGE THAT IT IS IN THE 

LAST-USED STATE, CANCELS SUB PROG 1 VIA A CANCEL 

IDENTIFIER, AND RETURNS TO THE MAIN PROGRAM. 
ENVIRONMENT DIVISION. 
CONFIGURATION DIVISION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 SWITCH PIC 9 VALUE 0. 
77 CANCL-ID PIC X<8) . 
PROCEDURE DIVISION. 

IF SWITCH=0 DISPLAY 'SUBPROG2 CALLED — IN INITIAL STATE* 
GO TO RETURN-POINT. 

DISPLAY 'SUBPROG2 CALLED — IN LAST-USED STATE 1 . 

DISPLAY 'SUBPROG2 CANCELLING SUBPROG1*. 

MOVE «SUBPROG1» TO CANCL-ID. 

CANCEL CANCL-ID. 
RETURN-POINT. 

ADD 1 TO SWITCH. 

EXIT PROGRAM. 



/* 

//LKED.SYSLMOD DD 

/* 



DSN=SUBPROGS (SUBPROG2) ,UNIT=23H* , VOL=SER=XXXXXX,DISP=OLD 



Figure 122. Sample Calling and Called Programs Using Dynamic CALL and CANCEL Statements 
(Part 2 of 3) 
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I//CALLJ0B3 

I //STEP 1 

| //COB. SYS IN 



I/* 

I//LKED.SYSLHOD 
I //GO EXEC PGH- 
I//STEPLIB 
//SISOUT 
I/* 



JOB user information 

EXEC COBUCL, PARM. COB= • DYNAM, RESIDENT • 

DD * 

IDENTIFICATION DIVISION. 

PROGRAM-ID. MAINPROG. 

AUTHOR. J. SMITH 

REMARKS. 

THIS IS A MAIN PROGRAM. IT CALLS SUBPROG1 AND 

SUBPROG2 TWICE. ON THE FIRST CALL, EACH SUBPROGRAM 

SHOULD BE A FRESH COPY (THAT IS, IN INITIAL STATE). 

ON THE SECOND CALL, EACH SUBPROGRAM SHOULD BE IN ITS 

LAST-USED STATE. WHEN SUBPROG2 IS CALLED THE SECOND 

TIME, IT CANCELS SUBPROG1. THEN MAINPROG CALLS 

SUBPROG1 AGAIN, AND AGAIN A FRESH COPY OF THIS 

SUBPROGRAM SHOULD BE MADE AVAILABLE. 

THE OUTPUT FROM THIS RUN SHOULD READ AS FOLLOWS: 

•BEGIN MAINPROG. 

MAINPROG CALLING SUBPROG1. 

SUBPROG1 CALLED — IN INITIAL STATE. 

MAINPROG CALLING SUBPROG2. 

SUBPROG2 CALLED — IN INITIAL STATE. 

MAINPROG CALLING SUBPROG1. 

SUBPROG1 CALLED — IN LAST-USED STATE. 

MAINPROG CALLING SUBPROG2. 

SUBPROG2 CALLED — IN LAST-USED STATE. 

SUBPROG2 CANCELLING SUBPROG1. 

MAINPROG CALLING SUBPROGl. 

SUBPROG1 CALLED — IN INITIAL STATE. 

MAINPROG CANCELLING SUBPROG1 AND SUBPROG2. 

END MAINPROG. • 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 SWITCH PIC 9 VALUE 0. 
77 CALLID PIC X(8) . 
PROCEDURE DIVISION. 

DISPLAY 'BEGIN MAINPROG*. 
START-CALLS. 

IF SWITCH IS LESS THAN 2 PERFORM CALL1, 

PERFORM CALL2, 

GO TO START-CALLS. 

PERFORM CALL1. 

DISPLAY 'MAINPROG CANCELLING SUBPROG1 AND SUBPROG2'. 

CANCEL 'SUBPROG1»,'SUBPROG2'. 

DISPLAY 'END MAINPROG'. 

STOP RUN. 
CALL1. 

MOVE 'SUBPROG1' TO CALLID. 

DISPLAY 'MAINPROG CALLING SUBPROG1'. 

CALL CALLID. 
CALL2. 

MOVE 'SUBPROG2' TO CALLID. 

DISPLAY 'MAINPROG CALLING SDBPROG2'. 

CALL CALLID. 

ADD 1 TO SWITCH. 

DD DSN=SUBPROGS (MAINPROG) ,UNIT=2314 , VOL=SER=XXXXXX,DISP=OLD 
= MAINPROG 

DD DSN=SUBPROGS,UNIT=2314,VOL=SER=XXXXXX,DISP=OLD 
DD SYSOUT=A 



Figure 122. Sample calling and Called Programs Using Dynamic CALL and CANCEL Statements 
(Part 3 of 3) 
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Although all identifiers of the called 
program in the ENTRY statement must be 



described with level numbers of 01 or 77, 
there is no such restriction made for 
identifiers of the calling program in the 
CALL statement. An identifier of the 
calling program may be a qualified name or 
a subscripted name. 



FILE-NAME ARGUMENTS 



A calling COBOL program that calls an 
assembler-language program can pass 
file-names, in addition to data-names, as 
identifiers. For a queued file, the 
file-name is passed as the address of the 
DCB (Data Control Block) and for a basic 
file, the file-name is passed as the 
address of the DECB (Data Event control 
Block) . A VSAM file name cannot be passed. 



LINKAGE IN A CALLING OH CALLED 
ASSEMBLER-LANGUAGE PROGRAM 



In a COBOL program, the expansions of 
the linkage statement provide the save and 
return coding that is necessary to 
establish linkage between the calling and 
the called programs. Assembler- language 
programs must be prepared in accordance 
with the basic linkage conventions of the 
operating system. Figure 123 shows the 
conventions for use of general registers as 
linkage registers. 



% r 

Register 
Number 



Register 
Dse 



Contents 



1 
13 

14 
15 



Identifier 
Save Area 

Return 
Entry Point* 



Address of the list that is passed to the called program. 

Address of an area (of 18 full words) to be used by the called 
program to save registers. 

Address of the location in the calling program to which 
control should be returned after execution of the called 
program. 



Address of the entry point in the called program to which 
control is to be transferred. 



— i 



1 Register 15 is also used as a return code register. The return code indicates 

whether or not any exceptional conditions occurred during execution of the called 
program. When control is returned to the COBOL program, it automatically moves the 
contents of register 15 into the special register RETURN-CODE. 

i i , 

Figure 123. Linkage Registers 
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C onvention s Osed in a Callin g 
Assem b ler-Language P r ogram 



chain pointer from there, and executes a 
8ET0RN to the caller of the main program. 



A calling assembler-language program, 
must reserve a save area of 18 words, 
beginning on a fullword boundary, to be 
used by the called program for saving 
registers. It must load the address of 
this area into register 13. If the program 
is to pass identifiers, an identifier list 
must be prepared, and the address of the 
identifier list must be loaded into 
register 1. The calling program must load 
the address of the return point into 
register 14, and it must load the address 
of the entry point of the called program 
into register 15. 



The identifier list is a group of 
contiguous fullwords, each of which is an 
address of a data item to be passed to the 
called program. The identifier list must 
begin on a full word boundary. The 
high-order bit of the last identifier, by 
convention, is set as a flag of one to 
indicate the end of the list. Figure 125 
shows a portion of an assembler-language 
program that illustrates the conventions 
used in a calling program. 

T he Assembler- Lan guage Caller As Main 
Program; In an all-COBOL environment, the 
first COBOL program in the run unit that is 
invoked for execution becomes the main 
program. It may be invoked via an EXEC JCL 
card, or by linkage from some other 
program. The fact that it is the first one 
invoked under the task establishes it as a 
main program. The main program calls a 
library subroutine which (1) initializes 
the subroutine communications data area 
ILBOCOM, and (2) saves a pointer to the 
register save area of the main program. (A 
main program also executes a GOBACK 
statement is if STOP BON had been coded. 
See below.) 

Any COBOL program invoked after the COBOL 
main program has begun to execute is 
considered a subprogram. A COBOL 
subprogram knows it is a subprogram rather 
than a main program because when it gets 
control, ILBOCOM has already been 
initialized. 

Execution of the STOP RON statement by any 
COBOL program causes a library subroutine 
to be called which terminates the run unit. 
This subroutine closes COBOL DCBs {such as 
SYSIN, SYSOUT, and SYSDBOOT) , and resets 
certain flags and fields in ILBOCOM. If 
ENDJOB (see below) is in effect, it 
performs further cleanup. Then it picks up 
the main program save area (register 13) 
pointer that was saved when ILBOCOM was 
initialized, follows the save area back 



Execution of the GOBACK statement in a 
COBOL subprogram causes a return to the 
routine that called it. However, execution 
of this statement in a COBOL main program 
causes STOP RON processing to occur (see 
above) . 

The compilation option ENDJOB causes the 
STOP RON subroutine to free all main 
storage acquired during the run unit, and 
to delete any subprograms or subroutine 
library modules that were loaded during the 
run unit. The only parts of the run unit 
left after a STOP RON with ENDJOB has 
executed are any load modules that were 
loaded by an assembler- language program 
rather than a COBOL program, and the 
library subroutine ILBOSTT. These must be 
deleted by an assembler-language calling 
program. 

If the compilation option RESIDENT is used, 
it must be used by all COBOL programs in a 
run unit. It causes linkage to library 
subroutines to be established at execution 
time, rather than at link edit time, and 
maintains a list of all subroutine library 
modules for which it has issued a LOAD. 

The compilation option DYNAM causes dynamic 
LOADs and DELETES to be done for 
subprograms specified in CALL and CALL 
CANCEL statements in COBOL programs in a 
run unit. It maintains a list of all 
subprograms it loads in the run unit. 

When a COBOL program is invoked by Job 
Management via an EXEC JCL card, the 
situation is straightforward. The COBOL 
program so invoked is the main program and 
begins the run unit. A STOP RON statement 
causes a return to the system. RESIDENT 
and DYNAM may be used to improve efficiency 
of main storage utilization. The ENDJOB 
option is not important, in this case, 
because job Management frees main storage 
and deletes load modules used by the 
jobstep task when it terminates. 

A COBOL program may also be invoked by 
use of CALL, LOAD and CALL, LINK, or 
ATTACH. If this is done, then the 
following cautions must be observed: 



1. Use the ENDJOB o 
region or partit 
GETMAIN-acquired 
modules when the 
after the run un 
calling program 
module ILBOSTT. 
an assembler Ian 
in any subprogra 
also be issued f 



ption to make sure the 
ion is cleared of 
storage and loaded 
run unit ends. Then, 
it has ended, have the 
issue a DELETE for 

If LOAD was used in 
guage program to bring 
ms, a DELETE should 
or those modules. 
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2. COBOL does not supp 
running of multiple 
one region or parti 
subtask is attached 
before the next one 
Multiple subtasks m 
limited circumstanc 
would definitely pr 
subtasking from wor 
DYNAH options, or u 
set by two differen 



ort concurrent 

COBOL subtasks in 
tion. If a COBOL 
, it must terminate 

is attached- 
ay work in very 
es. The following 
event multiple 
king: RESIDENT or 
se of the same data 
t subtasks. 



The COBOL subroutine library provides a 
means whereby an assembler-language program 
may become a main program; this is 
accomplished by a call to the library 
subroutine entry point ILBOSTPO, which 
causes ILBOCOM to be loaded and 
initialized. If this is done first, all 
COBOL programs subseguently called will 
behave as subprograms. This provides 
several other advantages for certain types 
of applications; execution of a GOBACK to 
the calling assembler-language routine will 
not cause STOP RUN processing — COBOL DCBs 
will remain open, no storage will be freed, 
no subroutines deleted; the 
assembler-language main program can 
continue calling its subprograms and adding 
to its open data sets until one of the 
subprograms executes a STOP RON. Execution 
of a STOP RUN will cause return to the 
caller of the assembler- language program, 
rather than to the assembler-language 
program itself. 



If this type of processing is desired, 
the assembler-language prograi must issue a 
CALL to the library subroutine entry point 
ILBOSTPO before making any call to a COBOL 
program. {Please note that ILBOSTPO 
destroys the contents of Registers and 
1.) The following considerations apply to 
the use of the CALL to ILBOSTPO (within a 
single run unit) ; 

1 . The subroutine ILBOSRV must be 
included in the link edit of the 
calling program. 



2. If RESIDENT is used, ILBOCOM must not 
be included in any link edit. Please 
note that the link edit of ILBOSRV 

to serve the ILBOSTPO interface must 
•leave a weak external reference for 
ILBOCOM unresolved. 

3. If NORESIDENT is used, all programs 
and subroutines must be link edited 
together. 

4. The CALL to ILBOSTPO may not be used 
if the COBOL program is invoked by 
LINK or ATTACH. 

5. If DYNAH is used, all COBOL programs 
must be link edited in separate load 
modules. 

The following table distinguishes the 
procedures for initialization with several 
representative types of program linkage. 

In Cases 1, 2, and 3, the CALL to 
ILBOSTPO interface is being used. In Case 
4, it is not. 

Case 1 . Caller should have a V-type 
address constant for ILBOSTPO and should 
call ILBOSTPO using it. Library 
subroutine ILBOSRV must be included in 
the link edit, but ILBOCOM must not be. 
The COBOL program may then be called 
as a subroutine. 

Case 2. Caller should have a V-type 
address constant for ILBOSTPO and should 
call ILBOSTPO using it. Library 
subroutine ILBOSRV. must be included in 
the link edit of the caller, but ILBOCOM 
must not be. No library subroutines 
should be included in the link edit of 
the called COBOL program. After the call 
to ILBOSTPO, caller should issue a LOAD 
for the called COBOL program. The COBOL 
program may then be called as a subroutine. 

Case 3. Caller should have a V-type 
address constant for ILBOSTPO and should 



i 



T » 1 

I Caller and COBOL | Caller and COBOL 
j Program Linked | Program Linked 
| Together J Separately 



J Case 2 
1 



-i 



I Called COBOL | Case 1 

I Program Compiled 1 

1 with RESIDENT j 

J option \ 



I 



■+- 



j Called COBOL J Case 3 
i Program Compiled J 
| with NORESIDENT | 
1 option 1 

i i 



J Case 4 
J 
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call ILBOSTP using it. The COBOL program 
may then be called as a subroutine. Hit fa 
the NORES option, all subroutines will be 
link edited into the load module. 

Case 4. Caller must LOAD the COBOL 
module, then call it. Caller may 
use LINK or ATTACH instead of LOAD, 
CALL, and DELETE. 

Figure 124 is an example of Case 2 and 
illustrates one fairly typical and useful 
configuration for assembler- language 
programs calling COBOL-language routines. 
C0B0L1 is a transaction processor of some 
type. ASM1 collects transactions and 
passes them to ASM 2, which passes them one 
at a time to COBOL 1. When all transactions 
are done, ASM2 calls C0B0L2 to execute a 
STOP HUN, perform ENDJOB cleanup, and 
return to ASM1. 

Because ASM2 has first called ILBOSTPO , 
all COBOL programs in the run unit will 
behave as subprograms. Thus when C0B0L1 
returns control to ASM2 after a call, it 
remains in main storage in its last-used 
state. There is no overhead for cleanup 
or for reinitialization on the succeeding 
call. COBOL 1 can return control By 
either an EXIT PROGRAM or a GOBACK. 
(Because it is behaving as a subprogram, 
GOBACK is equivalent to EXIT PROGRAM.) 
ENDJOB processing is not done for any of 
the exits from COBOL 1 . It is only done 
once , in response to the STOP RUN in 
C0B0L2 . 

Two of the several possible ways to 
compile and link edit this application are: 



1. Compiling with ENDJOB and NORESIDENT. 
ASM2, C0B0L1, COB0L2, and all required 
library subroutines would be link 
edited together. ASM1 would issue a 
LOAD for ASH2, then CALL it. Upon 
receiving control again, ASH1 would 
DELETE ASM2. 



Compiling with ENDJOB and RESIDENT. 
ASM2 and ILBOSRV would have to be 
link edited together. COBOL 1 could 
also be included. In that case, 
ASM1 would issue a LOAD for ASM2, 
then CALL it. ASM2 would have to 
issue a LOAD for C0B0L2 before 
calling it. When control is returned 
to ASM1 , it must issue a DELETE for 
ASM2, C0B0L2, and ILBOSTT. 




• EXIT PROGRAM 
or GOBACK 



• EXIT PROGRAM 
or GOBACK 



.C0B0L2 
. STOP RUN. 



Figure 124. Effect of STOP HON Statement 



Conventions Used in a Called Assembler- 
Language pro gram 



A called assembler-language program must 
save the registers and store other 
pertinent information in the save area 
passed to it by the calling program (the 
layout of the save area is shown in Figure 
127) . A called program must also contain a 
return routine that (1) loads the address 
of the save area back into register 13, 
<2) restores the contents of other 
registers, loading the return address in 
register 14, and (3) optionally, sets flags 
in the high- order eight bits of word 4 of 
the save area to 1*s to indicate that the 
return occurred. It can then branch to the 
address in register 14 to complete the 
return. 

Figure 126 (Part 6) shows a portion of 
an assembler-language program that 
illustrates the conventions used in called 
programs that are also calling programs. 
Figure 133 shows the JCL suggested for 
compiling, link-editing, and executing a 
calling assembler- language program and a 
called COBOL program. 
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AREA 



LA 13, AREA 



DS 18F 



CALLING SEQUENCE 

LA 1,ARGLST 

CALL C0BREGN2 



* PARAMETER LIST 

DS OF 

ARGLST DC X*80' 

DC AL3 (ARGUMENT) 
ARGUMENT DC CM' 



LOADS THE ADDRESS OF THIS PROGRAM'S SAVE AREA INTO 
REGISTER 13. 



RESERVES 18 HORDS FOR THE SAVE AREA 



LOADS INTO REGISTER 1 THE ADDRESS OF THE IDENTIFIER 
LIST TO BE PASSED. TRANSFERS CONTROL TO THE ENTRY 
POINT OF THE CALLED PROGRAM. (THE CALL MACRO 
INSTRUCTION GENERATES CODING THAT LOADS A V-TYPE 
ADDRESS CONSTANT — COBHEGN2 — INTO REGISTER 15 AND 
PLACES INTO REGISTER 14 THE RETURN ADDRESS, THAT IS, 
THE ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO 
EXPANSION. 



THIS PARAMETER LIST CONTAINS ONLY ONE ARGUMENT. 
FIRST BYTE OF LAST ARGUMENT (ONLY 
ARGUMENT IN THIS PROGRAM) SETS BIT 
TO 1. 



Note: since the calling program containing this coding could previously have been 
called by another program, it also could establish linkage between the save area it has 
received and the save area it passes to the called program. It would store in word 
three of the old save area the address of the new save area, and it would store in word 
two of the new save area the address of the old save area. 

Figure 125. Sample Linkage Coding Used in a Calling Assembler-Language Program 



COMMUNICATION WITH OTHER LANGUAGES 

An American National Standard COBOL 
program may communicate at object time 
with programs written in other source 
program languages, such as COBOL F, PL/I, 
and FORTRAN. However, such communication 
must follow the same conventions discussed 
above under "Linkage in a Called or Calling 
Assembler-Language Program." The 
relatively few problems that may arise 
in using American National Standard COBOL 
with COBOL F usually have to do with 
slightly different boundary alignments, 
slack-byte insertion, different meanings for 
the same reserved word, and so on. 

There is a greater disparity between 
American National standard COBOL and 
FORTRAN, much of it stemming from the basic 
differences in the applications for which 
these languages were developed. (FORTRAN 
is process oriented and does coaparatively 
little file processing! COBOL, on the other 
hand, is definitely file oriented and is 
not mathematically self-sufficient.) Care 
mast be taken, therefore, in attempting to 
pass arguments between American National 
Standard COBOL and FORTRAN programs. 



The use of COBOL and PL/I together 
requires a number of important 
considerations. See the publications QS/VS 
Linkage Editor and Loader and either OS 
PL /I O pti mizing Compiler Programmer's 
Guide, Order No. SC33-0006 or OS PL/I 
Checkout C offlpiler: Progr ammer's Guide , 
Order No. SC33-0007. 

Abnormal terminations in non-COBOL 
programs calling COBOL programs compiled 
with either the STATE or the SYMDUP option 
(see the chapter entitled "symbolic 
Debugging Features") cause generation of 
the following mis information; 

• Incorrect number for the statement 
responsible for the abnormal 
termination. The last COBOL statement 
in the called program executed before 
the return to the calling non-COBOL 
program is given in the "Last Card 
Number Executed" message. 



Incorrect PROGRAM-ID when such an 
abnormal termination occurs after 
return from the called COBOL program. 
The PROGRAM-ID message contains the 
aser-specified name for the called 
COBOL program. 
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SAMPLE CALLING AND CALLED PROGRAMS 



The following set of programs (Figure 
126) contains a sample COBOL main-line 
program, COB MAIN, which calls COBOL and 
assembler- language programs using arguments 
that represent a data-item and a file-name. 



Soae of the called programs (C0B0L1 , 
C0B0L1B, and ASSMPGM) are themselves 
calling programs. Program COBREGNO is 
called by several programs, each of which 
enters at a different entry point within 
the program. 



IDENTIFICATION DIVISION. 
PSOGRAH-ID. COBMAIN. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBH-370. 
INPDT-ODTPDT SECTION. 
FILE-CONTROL. 

SELECT FILE-X ASSIGN TO UR-2540R-S-INFILE. 
I-O-CONTROL. 
DATA DIVISION. 
FILE SECTION. 
FD j^ILE-X„ 

RECORD CONTAINS 80 CHARACTERS 

LABEL RECORD IS OMITTED. 
01 IN-REC. 

05 TYPEN PIC X. 
, 05 HOLDER PIC X. 

05 FILLER PIC X{78) . 
WORKING-STORAGE SECTION. 
77 SIGNAL PIC X(8) . 
PROCEDURE DIVISION. 



OPEN INPUT FILE-X. 

READ FILE-X AT END GO TO CLOSE-FILE. 



CALL 'COBOL1* USING IN-REC. 



CALL * COBREGN1' USING IN-REC. 



CALL ' ASSMRTN* USING SIGNAL. 



CLOSE-FILE. CLOSE FILE-X. 



STOP RUN. 



Figure 126. Sample calling and Called Programs (Part 1 of 7) 
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IDENTIFICATION DIVISION. 
PROGRAM-ID. COBOL 1. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
I-O-CONTROL. 
DATA DIVISION. 
FILE SECTION. 
WORKING-STORAGE SECTION. 
77 TRANS-COBL PIC X(7). 
LINKAGE SECTION. 
01 PASS -R EC. 

05 FILLER PIC X. 

05 TRANS-VALUE PIC X. 

05 FILLER PIC X|78) . 
PROCEDURE DIVISION USING PASS-REC, 



CALL »COBOL1A» USING TRANS-COBL. 



CALL «COBOLIB» USING TRANS-COBL. 



GOBACK. 



Figure 126. Sample Calling and Called Programs {Part 2 of 7) 



IDENTIFICATION DIVISION. 

PROGRAM-ID. COBOL1A. 

ENVIRONMENT DIVISION. 

CONFIG ORATION SECTION. 

SOURCE-COMPUTER. IBM-370. 

OBJECT-COMPUTER. IBM-370. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

I-O-CONTROL. 

DATA DIVISION. 

FILE SECTION. 

WORKING-STORAGE SECTION. 

LINKAGE SECTION. 

77 TRANS-COB1A PIC X{7) . 

PROCEDURE DIVISION USING TRANS-COB 1 A. 



GOBACK. 



Figure 126. Sample Calling and Called Programs (Part 3 of 7) 
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IDENTIFICATION DIVISION. 

PROGRAM-ID. COBOL 1B. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM-370. 

OBJECT-COMPUTER. IBM-370. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

I-O- CONTROL. 

DATA DIVISION. 

FILE SECTION. 

WORKING-STORAGE SECTION. 

77 TRANS-COB1EGN PIC X(7). 

LINKAGE SECTION. 

77 TRANS-COB1B PIC X(7). 

PROCEDURE DIVISION USING TRANS-COB1B. 



CALL »COBREGN0« USING TRANS-COBREGN. 



GOBACK. 



c 



Figure 126. Sample Calling and Called Programs (Part 4 of 7) 



IDENTIFICATION DIVISION. 
PBOGBAM-ID. COBREGNO. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
I-O- CONTROL. 
DATA DIVISION. 
FILE SECTION. 
WORKING-STORAGE SECTION. 
LINKAGE SECTION. 
77 TRANS-COB PIC X (7) . 
77 TRANS-ASSM PIC X{4). 
01 PASS-REC. 

05 FILLER PIC X. 

05 TRANS-VALUE PIC X. 

05 FILLER PIC X (78) . 
PROCEDURE DIVISION USING TRANS-COB. 



GOBACK. 
B. ENTRY , COBREGN1» USING PASS-REC. 



GOBACK. 
C. ENTRY •COBREGN2* USING TRANS-ASSM. 



GOBACK. 



L. 



Figure 126. Sample Calling and Called Programs (Part 5 of 7) 
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ASSMPGH START 

PRINT NOGEN 

ENTRY ASSMRTN 

* 

USING ASSMRTN,15 



* SAVE ROUTINE 




ASSMRTN SAVE 


(14,12) 


* 




* 




* 




* 




* 




* 




* 




* 




LB 


10,15 


DROP 


15 


USING 


ASSMRTN, 10 


LR 


11,13 


* 




* 





AREA 

PROCESS 
* 

* 
* 

* 

* 
* 



LA 



ST 



ST 

B 
DS 



13, AREA 



13,8(11) 



11,4<13) 

PROCESS 
18F 

2,0(1) 



ESTABLISHES ASSMRTN AS AN EXTERNAL NAME THAT CAN BE 
REFERRED TO IN ANOTHER PROGRAM. 



STORES THE CONTENTS OF REGISTERS 14, 15, 0, AND 1 
IN WORDS 4, 5, 6, AND 7 OF THE SAVE AREA. 
THESE ARE CONVENTIONAL LINKAGE REGISTERS. 
REGISTERS 2 THROUGH 12, WHICH ARE NOT 
ACTUALLY USED FOR LINKAGE, ARE SAVED IN SUBSEQUENT 
WORDS OF THE SAVE AREA. THE EXPANDED CODE OF THE 
SAVE MACRO INSTRUCTION USES REGISTER 13, WHICH 
CONTAINS THE ADDRESS OF THE SAVE AREA, IN 
EFFECTING THE STORAGE OF REGISTERS. 



LOADS THE ADDRESS OF THE SAVE AREA INTO REGISTER 11, 
WHICH WILL SUBSEQUENTLY BE USED TO REFER TO THE 
SAVE AREA. 

LOADS THE ADDRESS OF THIS PROGRAM'S SAVE AREA INTO 
REGISTER 13. 

STORES THE ADDRESS OF THIS PROGRAM'S SAVE AREA INTO 
WORD 3 OF THE SAVE AREA OF THE CALLING PROGRAM. 

STORES THE ADDRESS OF THE PREVIOUS SAVE AREA INTO 
WORD 2 OF THIS PROGRAM'S SAVE AREA. 



RESERVES 18 WORDS FOR THE SAVE AREA. 



LOADS INTO REGISTER 2 THE ADDRESS OF 
LIST PASSED TO THE PROGRAM. THE A 
IDENTIFIER-LIST IS ALWAYS PASSED I 
WHICH IS USED HERE AS THE BASE REG 
ADDRESS. SUBSEQUENT REFERENCES TO 
WILL USE REGISTER 2 AS THE BASE RE 
ADDRESS. (IF A VARIABLE-LENGTH ID 
COULD BE USED IN CALLING THIS PROG 
IDENTIFIER WOULD BE TESTED FOR A 
HIGH-ORDER BIT.) 



THE IDENTIFIER- 
DDRESS OF THE 
N REGISTER 1, 
ISTER TO GET THE 

THE IDENTIFIER 
GISTER FOR THAT 
ENTIFIER-LIST 
RAM, EACH 
NE IN THE 



(User-written program statements} 



CALLING SEQUENCE 

LA 1,ARGLST 



CALL COBREGN2 



LOADS INTO REGISTER 1 THE ADDRESS OF THE IDENTIFIER- 
LIST TO BE PASSED. 

TRANSFERS CONTROL TO THE ENTRY POINT OF THE CALLED 
PROGRAM. [THE CALL MACRO INSTRUCTION GENERATES 
CODING THAT LOADS A V-TYPE ADDRESS CONSTANT — 
COBSEGN2 — INTO REGISTER 15 AND PLACES INTO 
REGISTER 14 THE RETURN ADDRESS (THAT IS, THE 
ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO 
EXPANSION) ]. 



(User-written program statements) 



Figure 126. Sample Calling and Called Programs (Part 6 of 7) 
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CALLING SEQUENCE 

LA 1,ARGLST 



CALL C0BREGN2 



LOADS INTO REGISTER 1 THE ADDRESS OF THE 
IDENTIFIER- 
LIST TO BE PASSED. 

TRANSFERS CONTROL TO THE ENTRY POINT OF THE CALLED 
PBOGEAH. [THE CALL MACRO INSTRUCTION GENERATES 
CODING THAT LOADS A V-TYPE ADDRESS CONSTANT — 
COBREGN2 — INTO REGISTER 15 AND PLACES INTO 
REGISTER 14 THE 8ETURN ADDRESS {THAT IS, THE 
ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO 
EXPANSION) ]. 



{User-written program statements} 



RETURN ROUTINE 

L 13,4(13) 



RETURN{14,12) ,T,RC=(15) 



PARAMETER LIST 





DS 


OF 


ARGLST 


DC 


X'80» 




DC 


AL3 (ARGUMENT) 


ARGUMENT 


DC 

END 


C 1 1' 



LOADS THE ADDRESS OF THE PREVIOUS SAVE AREA 
BACK INTO REGISTER 13. 

THIS RETURN MACRO INSTRUCTION RESTORES THE SAVED 
REGISTERS (14, 15, AND THROUGH 12). THE RETURN 
ADDRESS IS RESTORED TO REGISTER 14, AND THE 
EXPANSION INCLUDES A BRANCH TO THAT INSTRUCTION. 
THE *T« IN THE RETURN MACRO INSTRUCTION CAOSES 
THE EIGHT HIGH-ORDER BITS OF WORD 4 OF THE SAVE 
AREA TO BE SET TO ONES AS AN INDICATION THAT THE 
RETURN HAS OCCURRED. THE RC= (15) PARAMETER 
INDICATES THAT THIS PROGRAM IS PASSING A RETURN 
CODE IN REGISTER 15. 



THIS PARAMETER LIST CONTAINS ONLY 1 ARGOSENT. 

FIRST BYTE OF LAST ARGUMENT (ONLY ARGUMENT IN 
THIS PROGRAM) SETS BIT TO 1. 



Figure 126. Sample Calling and Called Programs (Part 7 of 7) 



LINK-EDITING PROGRAMS 



Each time an entry point is specified in 
a called program, an external name is 
defined (except when a program is compiled 
using the DYNAM and RESIDENT compiler 
options) . An external name is a name that 
can be referred to by another separately 
compiled or assembled program. Each time 
an entry name is specified in a calling 
program, an external referen ce is defined 
except when a program is compiled using the 
DYNAM and RESIDENT compiler options. An 
external reference is a symbol that is 
defined as an external name in another 
separately compiled or assembled program. 
The linkage editor resolves external names 
and references and combines calling and 
called programs into a format suitable for 
execution together, i.e., as a single load 
module except when programs are compiled 
with dynamic CALL statements and/or the 
RESIDENT option (see the section entitled 
"Programs Compiled with the DYNAM and/or 
RESIDENT Options") . 



Load modules of both calling and called 
programs are used as input to the linkage 
editor. There are two kinds of input, 
primary and additional. Primary input 
consists of a sequential data set that 
contains one or more separately compiled 
object modules and/or linkage editor 
control statements. The primary input can 
contain object modules that are either 
calling or called programs or both. 
Additional input consists of object modules 
or load modules that are not part of the 
primary input data set but are to be 
included in the load module. The 
additional input may be in the form of (1) 
a sequential data set consisting of one or 
more object modules with or without linkage 
editor control statements, or (2) libraries 
containing object modules with or without 
linkage editor control statements, or (3) 
libraries consisting of load modules. Note 
that the secondary input (all libraries 
and/or data sets) must be composed of 
either all object modules or all load 
modules, but it cannot contain both types. 
The additional input is specified by 
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Word 
No. 


Area 
No. 




1 
2 


AREA 
AREA 


+ 4 



Contents 

Used by COBOL. 

Address (passed by the calling program) of the save area used by the 
calling program. This is the address of a save area that was 
passed to the called program by the program that called the called 
program. 

AREA +8 Address (stored by the called program) of the next save area, that 
is, the save area that the called program provides for a program 
that it calls. The called program need not reserve a save area if 
it does not, in turn, call another program. 

AREA +12 Return address (contents of register 14) stored by the called 
program. 

AREA +16 Entry point address (contents of register 15) stored by the called 
program. 

AREA +20 Contents of register (stored by the called program). 

AREA +24 Contents of register 1 (stored by the called program) ; that is, the 
address of the identifier list passed to the called program. 



18 



AREA +28 



AREA +68 



Contents of registers 2 through 12 (stored by the called program) - 



Figure 127. Save Area Layout and Contents 



linkage editor control statements in the 
primary input and a DD statement for each 
additional input data set. Additional 
input say contain either calling or called 
programs or both. 

Note: Each additional input data set may 

itself contain external references or names 

and linkage editor control statements that 
specify more additional input. 



SPECIFYING PRIMARY INPUT 



The primary input data set is specified 
for linkage editor processing by the SYSLIN 
DD statement. The linkage editor must 
always have a primary input data set 
specified by a SYSLIN DD statement whether 
or not there are called or calling programs 
and even if the primary input data set 
contains only linkage editor control 
statements. The SYSLIN DD statement that 
specifies the primary input is discussed in 
"Linkage Editor Data Set Requirements" (see 
"Example of Linkage Editor Processing" for 
a discussion of ho* to specify a primary 
input data set that contains more than one 
object module along with linkage editor 
control statements) . 



SPECIFYING ADDITIONAL INPUT 



Additional input data sets are specified 
by linkage editor control statements and a 
DD statement for each additional input data 
set. 



The linkage editor control statements 
that specify additional input are INCLUDE 
and LIBRABY. t A primary input data set may 
consist entirely of such statements. The 
INCLUDE and LIBRARY statements may be 
placed before, between, or after object 
modules or other control statements in 
either primary or additional input data 
sets. One method of using these statements 
is shown in Figure 134. 



N_ote: Additional input often contains 
members of libraries (see "Specifying 
Libraries as Additional Input" in 
"Libraries") . 



*The operation field in a linkage editor 
control statement must start after column 
1. The operand field must be preceded by 
at least one blank. 
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INCLUDE Statement 



ALIAS Statement 



The INCLUDE statement is used to include 

an additional input data set that is either 

a member of a library or a sequential data 
set. The format is: 



Operation | Operand 



1 

INCLUDE | ddname[ (member-name 

\ [, member-name]. ..) ] 
I [ ,ddname[ (member-name 

| [ ,member-aame... ]) ]]-• 

1 



where ddname indicates the name of the DD 
statement that specifies the library or 
sequential data set, and member-name is the 
name of the library member that is to be 
included. Member-name is not used when the 
additional input data set is not a member 
of a partitioned data set. 



LIBRARY statement 



The LIBRARY statement is used to include 
additional input that may be required to 
resolve external references. The format 
is: 



The ALIAS statement specifies additional 
names for the output library member, and 
can also display names of additional entry 
points. If a load module has more than one 
entry point or more than one CSECT and the 
user wishes to access that alternate entry 
at execution time via a dynamic CALL, he 
should specify an ALIAS with the same 
symbolic name as the desired entry point or 
CSECT. The format is: 



J Operation | Operand 



I 

i 

J ALIAS 

1 

i 



H 

| ( symbol 

| (external name 
.-i 



,symbol 



i 



, external nam^l 

j 



where symbol specifies an alternate name 
for the load module, and external name 
specifies a name that is defined as a 
control section name or entry name in the 
output module. 

If the linkage-editor input includes an 
ALIAS statement, the symbolic name 
specified is identified with the relative 
location of the entry point or CSECT name 
that matches the ALIAS. If there is no 
matching entry point or CSECT name, the 
ALIAS is identified with relative location 
zero in the load module. 

H°.J:§s If tne user plans to dynamically 
call a subprogram at an ENTEY point, an 
ALIAS card is required in the link-edit 
step for that entry point. 



Operation J Operand 

h 



LIBEARY | ddname (member-name | 

} [, member-name ].. .) | 

] [, ddname (member-name ] 

| £ ,member -name. ..])]. .. j 

j ; j 



where ddname indicates the name of the DD 
statement that specifies the library, and 
member- name is the name of the member of 
the library. 

The LIBRARY statement differs from the 
INCLUDE statement in that libraries 
specified in the LIBRARY statement are not 
searched for additional input until all 
other processing, except references 
reserved for the automatic library call, is 
completed by the linkage editor. Any 
additional module specified by an INCLUDE 
statement is incorporated immediately, 
whenever the INCLUDE statement is 
encountered. 



NAME Statement 



The NAME statement specifies the name of 
the load module created from the preceding 
input modules and serves as a delimiter for 
input to the load module. The NAME 
statement may be used to assign a symbolic 
name to a load module. This symbolic name 
is entered in the directory of the 
partitioned data set that contains the 
module, and allows the module to be 
accessed at execution time by an OS/VS 
LOAD, LINK, XCTL, or ATTACH macro. The 
format is: 



J operation 1 Operand 
I 

I NAME 

i 



_, 

J member-name ( (B) ] 

_i . 



where member-name specifies the name to be 
assigned to the load module that is created 
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from the preceding input modules, and (R) 
indicates that this load module replaces an 
identically named module in the input 
module library. (If the module is not a 
replacement, the parenthesized value (R) 
has no effect.) 

If the linkage-editor input includes a 
NAME statement, the symbolic name specified 
is always identified with relative location 
zero in the load module, unless there is an 
ENTRY statement specifying a different 
location. 



the name of the control section to be 
sequenced, and P specifies that the 
starting address of the control section or 
named common area is to be on a page 
boundary within the load module. When P is 
specified, the control sections or common 
areas are aligned on 4K page boundaries 
unless the ALI6N2 attribute is specified on 
the EXEC statement. 



PAGE Statement 



ENTRY Statement 



The ENTRY 
symbolic nam 
be executed 
its module n 
statement sh 
is reprocess 
more than on 
encountered, 
the main ent 
statements a 



statement s 
e of the fir 
when the pro 
ame for exec 
ould be used 
ed by the li 
e ENTRY stat 

the first s 
ry point; al 
re ignored. 



pecifies the 
st instruction to 
gram is called by 
ution. An ENTRY 

whenever a module 
nkage editor. If 
ement is 

tatement specifies 
1 other ENTRY 

Its format is: 



J Operation } Operand 



I j 

J ENTRY Jexternalname 

i i 



The PAGE statement aligns a control 
section or named common area on a 4K page 
boundary in the load module. For 0S/VS2, 
if the AIIGN2 attribute is specified on the 
EXEC statement for the linkage editor job 
step, use of the PAGE statement aligns the 
specified control sections or common areas 
on 2K page boundaries within the load 
module. Its format is: 



i i 

I Operation | Operand 



I PAGE jjcomaon-area-name 

| jjcsectname 



jjcom mo n- area- name 
jjcsectname 




where extern alname is defined as either a 
control section name or an entry name in a 
linkage editor input module. 



where common-area-name is the name of the 
common area to be aligned on a page 
boundary, and csectname is the name of the 
control section to be aligned on a page 
boundary. 



OS PER Stat em en t 



The ORDER statement specifies the 
sequence in which control sections or named 
common areas are to appear in the output 
load module. when multiple ORDER 
statements are used, their seguence further 
determines the sequence of the control 
sections or named common areas in the 
output load module; those named on the 
first statement appear first, and so forth. 
Its format is: 



J Operation JOperand 

I L 



I ORDER 
I 



rommon-area- 
:sectname 



name! f" 

f r cp) ] L 



jfcommon-area-namef "j 

jjcsectname f [ (P) ] J 



J 

I 

j 

1 

.- J 

j 



where common-area-name is the name of the 
common area to be sequenced, csectname is 



PROGRAMS COMPILED WITH THE DYNAH\ AND/OR 
RESIDENT OPTIONS V " 



In the usual called/calling situation, 
all references to any subprogram or library 
subroutines generated in an object program 
result in a ?-type address constant (VCON) 
that must be resolved by the linkage 
editor. Therefore, at link-edit time, the 
modules referred to by VCONs are made a 
part of a single load module containing the 
object program and all required subprograms 
and library routines. When the object 
program is executed, all those required 
routines are present in the user region for 
the entire execution step, even though they 
may have been used only at the beginning of 
the main program and never invoked again. 
With dynamic linkage, on the other hand, 
the user can invoke a called program when 
it is needed and retain it for only the 
period needed. 
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Subprograms invoked through the CALL 
literal statement are dynamically loaded 
using the Operating System LOAD macro if 
DYNAM is specified. Before the CALL 
Subprogram is executed, linkage is effected 
for all COBOL library subroutines reguired 
by the subprogram. Similarly, use of the 
CANCEL statement makes it possible to 
dynamically delete subprograms at object 
time. 



n 



I JCALL 

ICOBAJ 

J j literal 
t j 



I JCALL 

-> | COBB J 

1 | literal 




Figure 128. CALL with DYNAM and RESIDENT 
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When a program is compiled with DYNAM 
and RESIDENT, no external references are 
generated. Therefore, while the program 
may refer to other modules, no references 
are resolved by the linkage editor. In 
such a case, the only input to the linkage 
editor is the program itself. Any module 
the program refers to must exist in load 
module form in a library that is available 
to the system at execution time. 

The link-editing that takes place varies 
with the combinations of the DYNAM (NODYNAM) 
and RESIDENT (NORESIDENT) options in effect. 
What would seem to be the most 
representative link-edit situations are 
discussed in the sections that follow. 



Specifying DYNAM/RESIDENT 



When both DYNAM and RESIDENT are 
specified for the called/calling situation 
pictured in Figure 128, first the main 
program COBA is compiled and link-edited; 
then each of the two subprograms COBB and 
COBC is compiled and link-edited 
separately, thereby producing three 
separate modules. Then the main program is 
executed. 

In this situation, all external 
references are dynamically resolved. 
Therefore, no VCONs are generated for the 
address of an external symbol that would be 
used in a static situation {that is, a CALL 
literal without the DYNAM option) to effect 
branches to other programs. 



Specifying NODYNAM/RESIDENT 

When NODYNAM and RESIDENT are specified 
for the called/calling situation pictured 
in Figure 129, a dynamic situation occurs 
because of the inclusion of CALL identifier 
in the calling programs. That is, because 
the name of the called subprogram is not 
available until execution time, a CALL 
identifier statement cannot be used in a 
static situation. 

In Figure 129, if NORESIDENT had been 
either specified or implied by default, it 
would have been overridden with RESIDENT. 
The compiler automatically recognizes the 
requirement for the library management 
feature by the presence of either a CALL 
identifier or CANCEL identifier in the 
source program. 

Note: A printed indication of the compiler 
options in effect appears in the statistics 
section of the compiler output. (For 
examples of compiler statistics, see the 
chapter entitled "Output.") 



j JCALL 

j COB A I 

1 I identifier! 



| JCALL 
— > J COBB J 



>1C0BCJ 

I identifier! J 



Figure 129. CALL With NODYNAM and RESIDENT 
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Note: When including both dynamic and 
static CALL statements in the same run 
unit, the programmer should not dynamically 
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call any subprograms that are otherwise 
called statically. To do so might cause 
multiple copies of the called program to be 
created and, therefore, produce 
unpredictable results. 

The combination of RESIDENT and NODYNAM 
should be used only if required library 
subroutines are in fact permanently 
resident, or if all calls to COBOL 
subprograms are dynamic. If the library 
subroutines are not permanently resident, 
they will be loaded into the region or 
partition during program execution. This 
could cause storage fragmentation if a 
static call is made to a COBOL subprogram, 
because the subroutines required by a 
subprogram can only be removed from the 
region by a CANCEL statement for the 
subprogram, and a CANCEL is invalid for a 
subprogram that is statically called. 



Management Feature is not in effect, and 
all CALL statements result in static calls 
that must be resolved by the linkage 
editor, one load module is produced for 
the programs COBA, COBB, COBC, and all of 
the necessary COBOL library subroutines. 



The NGDYNAM/NORESIDENT set of options 
should be used only when the user does not 
intend to use the CALL or CANCEL identifier 
statement or the Library Management 
Feature. If either a CALL identifier or a 
CANCEL identifier statement appears in any 
one program, the Library Management Feature 
is in effect for that program only. This 
situation may result in a duplication of 
subprograms and COBOL library subroutines 
within the user region/partition, thereby 
causing unpredictable results. 



CALL CALL 
literal > literal > 



1 

\ COBA 
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J COBB 



COBC 
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1 


* 


i 

















Figure 130. CALL With NODYNAM and RESIDENT 
With CALL Literal Option 
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Figure 131. CALL With NODYNAM and 
NONRESIDENT 



Specifying N OP Y NAM/8 ORES IDE NT 



For the called/calling situation 
pictured in Figure 131, the COBOL Library 



33 6 



I//JOBY 

1//STEP1 

I 

I 

I 

I//SYSLIN 

I//SYSIN 

I 

I 

1 

1 

I/* 

1//STEP2 

I//SYSLMOD 

| //SYS LIN 

I//SYSIN 

| NAHE 

I/* 

J //STEP 3 

i //SYS LIN 

J//SYSIN 

i 

I 

I/* 

J//STEP4 

1//SYSLM0D 

| //SYS LIN 

I//SYSIN 

| NAME 

I/* 

I//STEP5 
I//STEPLIB 
J/* 



JOB 

EXEC PGH = IKFCBL 00, PARM=» LOAD, DY NAM, RESIDE NT* 



DD 
DD 



DSNAHE=SSLINKDS1,DISP= (MOD, PASS) ,UNIT=SYSSQ,SPACE= {TRK, {10,10) ) 
* 



{Source module for COBHAIN, a calling COBOL program} 

CALL 'COBS0B* 

EXEC PGM=HEWL 

DD DSNAfl£=S&GOFILE,DISP=(HOD,PASS) , UNIT=SYSSQ, SP ACE= {TRK, (10, 10, 10) ) 

DD DSNAME=&&LINKDS1,DISP= (OLD, DELETE) 

DD * 

COBHAIN 

EXEC PGH=IKFCBL00,PARH=» LOAD, DY NAM, RESIDENT* 

DD DSNAME=0&LINKDS2,DISP= (MOD, PASS) ,0 NIT=SYSSQ,SPACE= {TRK , {10,10) ) 

DD * 

{Source module for COBSOB, a called COBOL program} 

EXEC PGM=HEWL 

DD DSNAHE=£&GOFILE,DISP= (OLD, PASS) 

DD DSNAME=S&LINKDS2,DISP= (OLD, DELETE) 

DD * 

COBSOB 

EXEC PGM= COBHAIN 

DD DSNAME=&&GOFILE,DISP= (OLD, DELETE) 



Figure 132. Sample JCL for Called/Calling Programs Compiled with the DYNAH and RESIDENT 
Options 
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1//CALLPR0G 

I //STEP 1 

J 

1 

I 

J//SYSLIN 

J// 
1//SYSIH 

I 

I/* 
J//STEP2 

I// 

J//SYSGQ 

I//SYSIN 

I 

I 

!/* 

j //STEP 3 

J// 

1 

I 



JOB 
EXEC 



PGM=IKFCBLOO,PARH= (LOAD, N3DECK) 



DD DSN=S&TEMPLIB1,UNIT=SYSSQ, DISP= (NEW, PASS) , 

SPACE=(TRK, (10, 1) ) 

DD * 

(Source module for COBSUB, a called COBOL program) 

EXEC PGM=ASMBLR,PARM=(LOAD, NODECK) , 

COND= (9,LT,STEP1) * 

DD DSN=£STEHPLIB1,DISP=(MQD,PASS) 

DD * 

{Source module for ASSMHAIN, a calling assembler- 
language program) 

EXEC PGM=HEWL,PARB={LIST,XREF,LET) , 

COND={(9,LT,STEP1), (5, LT, STEP 2} ) 



DSN=&STEMPLIB1,DISP= (OLD, PASS) 

* 

PROGLIB1* 
ASSMHAIN 3 

PGM=*.STEP3.SYSLM)D,COND=( (9,LT,STEP1) , X 

>) , (5,LT,STEP3) ) 
SYSOUT=A 

pThis example was chosen to illustrate the testing of condition codes. 

J 2 See the discussion under the INCLUDE statement. 

J 'Because the COBOL program is compiled first and the linkage editor cannot identify the 

1 proper entry point, the ENTRY statement must be included. j 

i J 

Figure 133. Sample JCL Used for a Calling Assembler-Language Program and a Called COBOL 
Program 



J//PROGLIB1 

I//SYSLIN 

I 


DD 
DD 
INCLUDE 


f 


ENTRY 


j/* 

J//STEP4 

!// 

| //SYS OUT 

i. 


EXEC 
(5,LT,STE 
DD 



LINKAGE EDITOR PROCESSING 
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subroutines. (External" references to these 
subroutines are generated by the COBOL 
compiler when statements in the source 
module require certain functions to be 
performed, such as some data conversions.) 

If the additional input contains 
external references and/or linkage editor 
control statements, the references are 
resolved in the same way. Data sets 
specified by the INCLUDE statement are 
incorporated when the statement is 
encountered. Data sets specified by the 
LIBRARY statement are used only when there 
are unresolved references after all of the 
other processing is completed. 
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//JOBX 
//STEP1 



//SYSLIN 
//SYS IN 



/* 
//STEP2 



//SYSLIN 
//SYSIN 



/* 
//STEP3 



//SYSLIN 
//SYSIN 



/* 

//STEP4 



//SYSLIB 
//SYSLMOD 

// 

//OBLIB 

//ADDLIB 

//SYSLIN 

// 



/* 



JOB 
EXEC 



DD 
DD 



PGH=IKFCBL00,PARM=LOAD 



DSNAME=&SGOFILE,DISP= (MOD, PASS), UNIT=SYSSQ,SPACE=(TRK, (10, 10| ) 



(Source module for COBHAIN) 



EXEC 



DD 

DD 



PGM=IKFCBL00 ,PARM=LOAD 



DSNAHE=*. STEP 1 .SYSLIN ,DISP= (MOD, PASS) 



{Source module for COBOL 1) 

EXEC PGM=IKFCBL00,PARM=LOAD 



DD 
DD 



DSNAME=*.STEP2.SYSLIN,DISP=( MOD, PASS) 
* 



(Source module for COBOL1A) 



EXEC PGM=IEHL 



DD DSNAME=SYS1.COBLIB,DISP=OLD 

DD DSNAHE=PGHLIB(CALPGf!) ,DISP= (HEW, KEEP) ,UNIT=334Q,X 

SPACE=(1024, (50,20,2)) ,VOLUME=SE R=LI BPAK 

DD DSNAME=OBJLIB, DISP=OLD 

DD DSNAME=MYLIB,DISP=OLD 

DD DSNAME=S£GOFILE, DISP= (OLD, DELETE) X 

DD * 

INCLUDE OBLIB (CO BOL 1 B, ASSSPGM) 

LIBRARY ADDLIB (COBREGN0) 



Figure 134. Specifying Primary and Additional Input to the Linkage Editor 
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STSP1 compiles a source module called 
COBMAIN, STEP2 compiles a source module 
called COBOL 1, and STEP 3 compiles a source 
module called COBOL1A. The object module 
from each step is placed in the sequential 
data set called &SG0FILE. (Since MOD and 
PASS are specified for SSGOFILE in the 
SYSLIN DD statement in STEP1, the object 
modules COBOL1 and COBOL1A are placed in 
the data set behind the object module 
COB-MAIN- When SYSSQ is not a mass storage 
device, the SPACE parameter is ignored.) 
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In STEP4, the linkage editor uses the 
&SGOFILE data set as primary input, and 
thecataloged libraries MYLIB, OBJLIB, and 
SYS1.CQBLIB as additional input. (The 
INCLUDE and LIBRARY statements become part 
of the primary input through the DD * 
statement following the SYSLIN DD 
statement. 



The object modules of 
&&GOFILE and the members 
ASSHPGH of OBJLIB are pr 
there are unresolved ref 
input is processed, the 
searches the automatic c 
includes the COBOL subro 
member COBREGNO of MYLIB 
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the data set 

COBOL 1B and 
ocessed first. If 
erences after this 
linkage editor 
all library, which 
utine library and 
, to resolve these 
pecified in the 
YLIB in the ADDLIB 



After linkage editor processing is 
completed, a new library, PGJMLIB, is 
created with CALPGM as a member. CALPGH 
contains COBMAIN, COBOL1 , C0B0L1A, COBOL 1B, 
ASSMPGM, and, possibly, COBOL subroutines 
and COBREGNO. 



Through the linkage mechanism, CALL 
COBOL1..., all subprograms plus COBMAIN 
must be link-edited together to form one 
module 42,000 bytes in size. Therefore, 
COBMAIN would require 42,000 bytes of 
storage in order to be executed. 

If the subprograms needed do not fit 
into main storage, the following two 
techniques of overlay are available to the 
COBOL programmer: 

• Preplanned overlay using the linkage 
editor 

• Dynamic overlay using assembler 
language macro instructions during 
execution 

Note: The largest load module that can be 
processed under OS/VS1 is 524,288 bytes. 
If a load module exceeds this limit, it 
should be divided. Onder OS/VS2, larger 
load modules are permitted. The ON 
OVERFLOW phrase should be used with the 
CALL statement to handle any such size 
errors. 



OVERLAY STRUCTURES 
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Note ; The use of execution-time 
debugging aids (SYMDMP, STATE, FLOW, 
COUNT, and so forth) when utilizing 
overlay structures is not recommended. 
Doing so may result in unpredictable 
operations within the STAE and debugging 
routines, or even abends. 

Considerations for Overlay 



Assume that the six programs illustrated 
in Figure 125 have the following load 
module sizes: 



Program 



COBKAIN 

C0BOL1 

COBOL 1 A 

COBOL1B 

COBREGNO 

ASSMPGM 



Module Size (in Bytes) I 



11,000 
4,000 
6,000 
5,000 
3,000 

13,000 



The preplanned linkage editor facility 
permits the reuse of storage locations 
already occupied. By judiciously 
modularizing a program and using the 
linkage editor overlay facility, a program 
that is too large to fit into storage at 
one time can be executed. 

In using the preplanned overlay 
technique, the programmer specifies to the 
linkage editor which subprograms are to 
overlay each other. The subprograms 
specified are processed as part of the 
program by the linkage editor, so they can 
be automatically placed in main storage for 
execution when requested by the program. 
The resulting output of the linkage editor 
is called an overlay structure. 



It is possible, at link 
set up an overlay structur 
COBOL source language link 
the linkage editor OVERLAY 
These statements enable a 
subprogram that is not act 
The details for setting up 
editor control statements 
this procedure can be foun 
publication OS/VS Linkage 
Loader. 
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In a linkage editor run, the programmer tables are used by the control program to 

specifies the overlay points in a program bring the overlay subprograms into storage 

by using OVERLAY statements. The linkage automatically when called, 
editor treats the entire input as one 

program, resolving all symbols and Figure 135 is an overlay tree structure 

inserting tables into the program. These illustrating how the six programs in Figure 
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Figure 135. Overlay Tree Structure 



126 could be positioned in main storage at 
execution time using preplanned linkage 
editor overlay. 
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Routine COBREGNO is placed with CGBMAIN 
in the root segment of the overlay 
structure because it is called by three of 
the routines in the program, the largest of 
which is ASSMPGH. Utilizing COBREGNO as an 
individual overlay segment would not have 
resulted in a net decrease in the amount of 
main storage reguired for execution because 
the minimum amount of main storage needed 
would have to contain COBHAIN, ASSHPGH, and 



COBREGNO at the same "time. creating 
another overlay segment for COBREGNO would 
only have added to the amount of time 
required for program execution. 



Dynamic pyer lay Tec hnique 



In preparation for the dynamic overlay 
technique, each part of the program brought 
into storage independently should be 
processed separately by the linkage editor. 
(Hence, each part must be processed as a 
separate load module.) To execute the 
entire program, the programmer must: 

1. Specify the main program in the EXEC 
statement. 

2. Bring the separately processed load 
modules into storage when they are 
reguired, by using the appropriate 
supervisor linkage macro instructions. 
This is accomplished during execution. 
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| //OVERLAY 
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I //STEP 1 


EXEC 


I//SYSLIB 


DD 


I//SYSPRINT 


DD 


J//SYS0T1 


DD 


I//SYSLMOD 


DD 


1// 




J//SYSLIN 
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DD 


1 
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| [COBREGNO 



JOVERLAY ALPHA 

| {COBOL1 

I 

| OVERLAY BETA 

{ {COBOL1A 
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fQVERLAY BETA 

1 {COBOL1B 

i 

I OVERLAY ALPHA 

J {ASSMPGM 

I/* 

i — 



NY83937800, COSMO, MSGLEVEL=1 

PGH=IEWL,PARM=*OVLX, LIST, XREF, LET' 

DSNAHE=SYS1.C0BLIB,DISP=SHR 

SYSOUT=A 

0NIT=SYSDA,SPACE=(1024, (50,20) ) 

DSNAHE=SGODATA(RUN) , DISP= (NEW, PASS) , UNIT=SYSDA, X 

SP&CE={1024, (50,20,1)) 

* 

object deck} 
object deck) 



object deck} 
object deck) 
object deck) 
object deck) 



Figure 136. Saaple Deck for Linkage-Editor Overlay Structure 
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When the COBOL subprogram is finished 
executing, it returns control to the 
assembler language subprogram, which in 
turn returns to the main program. The 
process is repeated for each CALL to the 
assembler-language subprogram. 



Dynamic overlay requires that a 
programmer have detailed knowledge of the 
linkage conventions, assembler language, 
and the LINK macro instruction with its 
features and restrictions. 



Figure 137 contains an example of a 
COBOL main program, PROGMAST, and an 
assembler language subprogram, LINKRTN. 
The two programs are link-edited together 
as a single load module. At execution 
time, the assembler-language subprogram 
dynamically fetches COBOL subprograms (OPM, 
BILL, CRDT, THNF, and LCK, none of which 
are shown in the example) for the main 
program using the LINK macro instruction. 
The COBOL subprograms are stored in a 
private library, DYNLINK. 

The parameter list passed to LINKRTN 
contains three identifiers, TRANS-REC, 
COM-SORD, and SWITCH, two of which 
(TRANS-REC and SWITCH) are referenced by 
LINKRTN, and two of which (TRANS-REC and 
COM-WORD) are referenced by the COBOL 
subprograms fetched. LINKRTN passes the 
same parameter list it receives to the 
COBOL subprograms fetched. 

LINKRTN determines from identifier 
TRANS-REC which subprograms to fetch, and 
from SwTTCH when to open and close the 
library DYNLINK. 



Note: In structuring a pr 
the preplanned overlay tec 
dynamic overlay technique, 
consideration must be give 
of the TRANSFORM table and 
tables, which are members 
object-time library (see M 
COBOL Library Subroutines" 
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Similarly, one or more of 
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tables is present in a COBOL load module if 
a class test is performed or if the OCCURS 
DEPENDING ON option is used. 

For these tables, which contain no 
executable code and are not branched to but 
are merely referenced, the compiler 
designates A-type address constants 



(ADCONs) and EXTRN references, rather than 
V-type address constants (VCONs) . 
Accordingly, the overlay structure segment 
containing the table (s) must be either the 
root segment or a segment that is higher in 
the same leg as the segment containing the 
reference (s) to the table (s). 



01 



IDENTIFICATION DIVISION. 
PROGRAH-ID. PEOGHAST. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-Y ASSIGN TO UR-2540R-S-INFILE. 
I-O-CONTROL. 
DATA DIVISION. 
FILE SECTION. 
FD FILE-Y 

RECORD CONTAINS 80 CHARACTERS 

LABEL RECORD IS OMITTED. 

TRANS-REC. 

05 ACCOUNT- NUMBER PIC 9(10). 

TRANSACTION PIC 9(4). 

NAME PIC X (20) . 

LOCATION PIC X(20) . 

METER-READING PIC 9(6). 

DAYTE PIC 9(6) . 

FILLER PIC X (8) . 

AMOUNT PIC 9(6) . 
WORKING-STORAGE SECTION. 
77 CGM-WORD PIC X(12). 
77 SWITCH PIC 9 VALUE ZERO. 
PROCEDURE DIVISION. 



OPEN INPUT FILE-Y. 

B, READ FILE-Y AT END GO TO END-RUN. 

C. CALL *GETUM» 0SING TRANS-REC COH-WORD SWITCH. 



05 
05 
05 
05 
05 
05 
05 



END- RUN. CLOSE FILE-Y. 
MOVE 2 TO SWITCH. 
PERFORM C. 
STOP RUN. 



Figure 137. Sample COBOL Main Program and Assembler-Language Subprogram Using Dynamic 
Overlay Technique (Part 1 of 3) 
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LINKRTN 


START 







PRINT 


NOGEN 




ENTRY 


GETUM 


* 






* 






* 






* 






* 






# 






* 






* 






* 






* 






* 








USING 


GETUM, 15 


GETUM 


SAVE 


(14,12) 




LR 


10,15 




DROP 


15 




USING 


GETUM, 10 




LR 


11,13 




LA 


13, SAVE AREA 




ST 


13,8(11) 




ST 


11,4(13) 




L 


5,0(1) 




USING 


PARAMLST,5 


* 








B 


OPENLIB 


SAVEAREA 


DS 


18F 


OPENLIB 


L 


6,8(1) 




CLI 


0(6) ,C 1' 




BE 


INITREG 


* 








BH 


CLOSLIB 


* 








OPEN 


(DYNLINK) 


* 








01 


(6) ,C» 1« 



TABLE LOOK-UP ROUTINE 



INITBEG 


LA 


2,RTNLST 




LA 


3,6 


FINDRTN 
* 


CLC 


TRANSACT, (2) 




BE 


GETRTN 




LA 


2,12(0,2) 




BCT 


3, FINDRTN 




MVC 


ERRMSG+28 (4) , TRANSACT 


ERRMSG 


WTO 


» INVALID TRANSACTION' 


EXIT 


L 


13,4(13) 




SR 


15,15 



RETURN (14, 12) ,T,RC= (15) 



DYNAMIC OVERLAY ROUTINE 



GETRTN 



L 1,24(11) 

LA 4,4(0,2) 

LINK EPLOC=(4) ,DCB=DYNLINK 



EXIT 



UPON ENTRY TO THIS PROGRAM, REGISTER 1 POINTS 
TO A FIXED-LENGTH PARAMETER LIST OF THREE 

WORDS. 

THE FIRST WORD CONTAINS THE ADDRESS OF 
RECORD TRANS-REC. 

THE SECOND WORD CONTAINS THE ADDRESS OF 
COM-WQRD, TO WHICH THIS PROGRAM DOES NOT 
REFER BUT WHICH IS USED BY ROUTINES THIS 
PROGRAM LATER LINKS TO. 

THE THIRD WORD CONTAINS THE ADDRESS OF 

SWITCH USED BY THIS PROGRAM TO CHECK THE 
STATUS OF THE PRIVATE LIBRARY DYNLINK 



REGISTER 5 LOADED WITH ADDRESS OF TRANS-REC 
REGTER 5 IS USED AS THE BASE REGISTER TO 
REFERENCE TRANS-REC, 



REGISTER 6 LOADED WITH ADDRESS OF. SWITCH- 
CHECK SWITCH STATUS. 
IF SWITCH = 1, DYNLINK IS ALREADY OPEN; 

INITIALIZE REGISTERS. 
IF SWITCH > 1, DYNLINK IS NO LONGER NEEDED; 

CLOSE DYNLINK. 
IF SWITCH = THE FIRST TIME THROUGH, OPEN 

DYNLINK. 
SET SWITCH SO THAT OPEN IS BYPASSED ON FUTURE 

ENTRY. 



INITIALIZE REGISTERS 2 AND 3 FOR LOOK-UP. 

TRANSACT CONTAINS THE TRANSACTION CODE THAT 
DETERMINES WHICH ROUTINE TO FETCH. 



PRODUCE ERROR MESSAGE IF TRANSACT CONTAINS 
AN INVALID CODE. 

SET REGISTER 15 TO ZERO. 

THE RC=(15) PARAMETER INDICATES THAT THIS 

PROGRAM IS PASSING A RETUBN CODE IN REGISTER 

15. 



RESTORE REGISTER 1 TO ORIGINAL STATUS. 

PASS REGISTER 4 TO NAME OF ROUTINE TO BE 
FETCHED. HAVE THE CONTROL PROGRAM 
FETCH THE ROUTINE POINTED TO BY 
REGISTER 4 FROM PRIVATE LIBRARY DYNLINK. 



Figure 137. Sample COBOL Main Program and Assembler-Language Subprogram Using Dynamic 
Overlay Technigue (Part 2 of 3) 
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CLOSLIB 


CLOSE 


(DYNLINK) 




B 


EXIT 




DS 


OF 


RTNLST 


EQU 


* 


* 






* 






4c 








DC 


C'0100' 




DC 


CLS'OPN' 




DC 


C'0200» 




DC 


CL8'BILL' 




DC 


C'0300' 




DC 


CL8»CRDT» 




DC 


C'0400' 




DC 


CL8»TRNF' 




DC 


C'0500' 




DC 


CL8VLCK' 


DYNLINK 


EQU . 


* 




DCB 


DDNAME=SY 


* 






* 






PARAMLST 

* 


DSECT 




* 
TRANSREC 


DS 


0CL80 


ACCTNUM 


DS 


CL10 


TRANSACT 


DS 


CL4 


NAME 


DS 


CL20 


LOCATION 


DS 


CL20 


HETERBD 


DS 


CL6 


DATE 


DS 


CL6 




DS 


CL8 


AHOONT 


DS 
END 


CL6 



CLOSE PRIVATE LIBRARY, 



AS THE TABLE SEARCHED BY THE TABLE LOOK-UP 

ROUTINE, RTNLST CONTAINS A LIST OF ALL VALID 
TRANSACTION CODES AND THE NAMES OF THE 
ROUTINES FETCHED TO HANDLE THE TRANSACTIONS 

TRANSACTION CODE 

ROUTINE NAME ASSOCIATED WITH ABOVE TRANSACTION 



DCB TO DEFINE PRIVATE LIBRARY REFERRED TO IN 
LINK MACRO INSTRUCTION. 

DSECT USED BY REGISTER 5 TO REFER TO TRANS- 
BEC. THE RECORD DESCRIPTION CORRESPONDS TO 
THAT OF TRANS-BEC IN PROGMAST. 



Igte: Had a job or step library (requiring either a JOBLIB or STEPLIB DD statement in 
the job control for execution of the main program) been used instead of a private 
library (which for this example requires a DD statement named DYNLNKDD) , responsibility 
for the opening and closing of the library would have been with the control program and 
not with LNKBTN. 

The use of a private library, in conjunction with the LINK DCB parameter, reduces to 
a minimum the amount of search time needed to retrieve member modules from a library. 



Figure 137. Sample COBOL Main Program and Assembler-Language Subprogram Using Dynamic 
Overlay Technique (Part 3 of 3) 
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LOADING PROGRAMS 



The loader resolves external names and 
references and combines calling and called 
programs into a format suitable for 
execution as a single load module. For 
information on invoking the loader, see 
"Using the Cataloged Procedures." 



When the dynamic call is used, all 
subprograms to be called dynamically must 
have been processed by the linkage editor. 
The loader may be used only to resolve 
references to subprograms invoked by static 
calls. Otherwise, load modules of both 
calling and called programs are used as 
input to the loader. There are two kinds 
of input, primary and additional. P rimar y 
input consists of one or more separately 
compiled object modules and/or load 
modules. Additional input consists of 
object modules or load modules that are not 
part of primary input data sets but are to 
be included in the load module. The 
additional input may be in the form of 
{1) libraries containing object modules, or 
(2) libraries containing load modules. 
Additional input may contain either calling 
or called programs or both. 



not invoked and unresolved external 
references in the Link Pack Area may 
prevent successful subroutine execution. 
Therefore, in order to prevent the loader 
from searching the Link pack Area, the 
NORES loader option should be specified in 
conjunction with the NORES compiler option. 
This will cause the loader to search for 
required modules in the SYSLIB data set, 
bypassing the Link Pack Area search. If 
COBOL subroutines that have external 
references which would need to be resolved 
do not reside in the Link pack Area, either 
the RES or NORES loader option is 
acceptable. (Subroutine external 
references are listed in Figure 174.) 



SPECIFYING PRIMARY INPUT 



The primary input data set is specified 
for loader processing by the SYSLIN DD 
statement. The loader must always have a 
primary input data set whether or not there 
are calling or called programs. The SYSLIN 
DD statement that specifies primary input 
is discussed in the section "Data Set 
Requirements." 



If these subroutines re 
Pack Area, their external 
not resolved. When the HE 
is specified, the loader a 
the Link Pack Area for mod 
searching the SYSLIB data 
compiler option is specifi 
ILBONTRO controls all subr 
intercommunication so that 
external references in the 
present no problem. If, h 
compiler option is specifi 



side in the Link 
references are 
S loader option 
lways searches 
ules before 
set. If the RES 
ed, subroutine 
outine 
unresolved 
Link Pack Area 
owever, the NORES 
ed, ILBONTRO is 



SPECIFYING ADDITIONAL INPUT 



Additional input data sets are specified 
by the SYSLIB DD statement. The SYSLIB DD 
statement is discussed in the section "Data 
Set Requirements." 

Note ; The overlay facility can not be used 
with the loader. 
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LIBRARIES 



Libraries are an integral part of the 
operating system, some libraries have 
system-supplied names and system-supplied 
data. Other libraries have system-supplied 
names but may contain user-specified data. 
Still other libraries have both 
user-supplied names and user-supplied data. 



Libraries, in general, are made up of 
partitioned data sets. Any library with a 
user-supplied name and user-supplied data 
is always a single partitioned data set, 
which is a collection of independent sets 
of seguentially organized data, called 
members. All of the members within a 
partitioned data set have the same 
characteristics as that of record format. 
When used to store programs, a partitioned 
data set containing load modules can 
contain only load modules; it cannot 
contain both load modules and object 
modules. 



This statement specifies that a library 
named FILELIB is to be created and 
cataloged in this job step. Its first 
member is named FIL.E1. Initial space 
allocated for data sets is to be 40 tracks, 
with additional allocation to be made, as 
necessary, in units of 10 tracks. In 
addition, space for three 256-byte records 
is to be allocated for the directory. The 
volume serial number is 111111. 

A member of a partitioned data set can 
be replaced or deleted. The system 
actually accomplishes this by modifying or 
deleting the directory pointer to the 
member. The space occupied by the original 
member is not available for reuse either 
until the MOVE or COPY control statement of 
the IEHMOVE utility program is used or the 
compress facility of the IEBCOPY utility 
program is used. The space previously 
occupied by the replaced or deleted member 
is thus made available. {For further 
details, see the publication OS/VS 
Utilities. ) 



Each partitioned data set is headed by a 
directory of entries pointing to the 
members that make up the library. Each 
member has a unique member name. A 
partitioned data set must reside on a 
single mass storage device, but some 
libraries can consist of a concatenation of 
more than one partitioned data set. 



Figure 138 shows the format of a library 
that is a single partitioned data set of 
four members. Space for the members of 
such a library and its directory is 
requested in the SPACE parameter of the DD 
statement when the library is created. 
Additional members can be added to a 
library at a later time. Additional space 
cannot be allocated for the directory, 
however. Directory space is allocated for 
the entire library when the library is 
created. If the original allocation was 
not large enough, the IEHMOVE utility 
program can be used to expand the directory 
size. If the directory is filled, no 
additional members can be added to the 
library. Following is an example of a DD 
statement that might be used to create a 
library: 



//DD1 

// 

// 

// 

// 



DD DSNAHE=FILELIB(FILE1) 
DISP={NE¥,CATLG) , 
UNIT=2314, 

SPACE=(THK, {40, 10,3)) 
VOLUHE=SEE=111111 



KINDS OF LIBRARIES 



A programmer can use libraries already 
provided by the system, or he can create 
libraries of his own. In addition, certain 
library names recognized by the system may 
be assigned to partitioned data sets 
provided by the system, by the programmer, 
or both. These libraries and their uses 
are discussed in the following paragraphs. 



SYSTEH LIBRARIES USED IN COBOL APPLICATIONS 



Link Librar 1 



The link library is a partitioned data 
set that contains load modules to be 
executed. Unless non-resident control 
program routines and IBM-supplied 
processing programs specified otherwise, a 
load module name in an EXEC statement is to 
be fetched from the link library. 
Operating system programs, such as the 
COBOL compiler, are usually contained in 
this library. 

The link library can be used by the 
programmer to store executable load modules 
at link-edit time. However, any attempt to 
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Notes: 

1. 

2. 



Space available in directory. 

Space available from deleted members. Space can be recovered 

through utility programs IEHMOVE and IEBCOPY. 

Space available in library. 



Figure 138. Format of a Library 



write in this library will cause a message 
to be issued to the operator if the library 
is write-protected or if its expiration or 
retention date has not yet occurred. Under 
these conditions, no data may be written 
unless authorized. 



The link library is identified in a job 
control statement as SYS 1.LINKLIB, or by 
default as specified by the system link 
list. 



Sort Library 



The sort library is a partitioned data 
set that contains load modules from which 
the sort program is produced. 

It may be identified- by the name 
SYS1.SQ8TLIB {see "Using the sort/Merge 
Feature") . 



COBOL Subroutine Library 



Procedure Library 



The procedure lib 
data set whose membe 
procedures at an ins 
include the cataloge 
by IBM. Procedures 
installation can be 
library with the IEB 
(see "Using the Cata 



rary is a partitioned 
rs are the cataloged 
tallation. They may 
d procedures provided 
written at the 
added to the procedure 
UPDTE utility program 
loged Procedures"). 



The system name for the procedure 
library is SYS1.PRGCLIB. 



The COBOL subroutine library is a 
partitioned data set that contains the 
COBOL library subroutines in load module 
form. These subroutines may be included in 
a COBOL load module or dynamically loaded 
to perform such functions as data 
conversion and double precision arithmetic. 
The COBOL programmer does not refer 
directly to these subroutines; in most 
cases calling sequences to them are 
generated at compile time from certain 
Procedure Division statements, and they are 
incorporated into the load module at 
link-edit time or loaded at program 
initialization time. A listing of 
subroutine names, functions, entry points, 
and size is given in Appendix B; also noted 
are those subroutines explicitly called by 
the COBOL program. 
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Availability at Execution-Time ; Usually, 
COBOL library subroutines needed in the 
user's program will be automatically 
link-edited into the load module, and the 
user need not concern himself with their 
availability. However, certain situations 
will require that subroutines not normally 
linked be available during program 
execution. To satisfy this requirement, 
the user can either make sure that the 
COBOL library is available to the system 
loader at execution time, or specifically 
include the subroutines in his load 
module — by using an INCLUDE SYSLIB 
(subroutine names) in the link edit SYSLIN 
data stream. 

The situations, and the subroutines 
required, are as follows: 

1. STATE compiler option was specified. 
Subroutine ILBOSTNO will be required 
if an abend occurs. 

2. TEST compiler option was specified. 
ILBOCOMO will be required. 

3. COUNT compiler option was specified. 
ILB0TC2 and ILB0TC3 will be required. 

4. SYMDMP compiler option was specified. 
ILBOD01, ILBOD10 through ILB0D14, 
and ILBOD20 through ILBOD26 will be 
required. 

5. COUNT, FLOW, STATE, or SYMDMP compiler 
option was specified. If an informative 
message needs to be issued, ILBODBEO 
will be required. 

6. Execution- time options (PARM field on 
EXEC statement) will be passed. 
ILBOPRMO will be required. 

In the event the DYNAMIC or RESIDENT 
compiler option was specified, then all 
subroutines will be loaded (and required 
to be available) at execution time. 

The system name for the COBOL subroutine 
library may be SYS1.C0BLIB. 



LIBRARIES CREATED BY THE USES 



A programmer can crea 
link library, the proced 
the job library. He can 
partitioned data sets fo 
library, the automatic c 
the job library- In add 
create partitioned data 
libraries for additional 
linkage editor, and he c 
whose members are source 



Au tomatic Ca ll Lib rary 



The automatic call li 
the SYSLIB DD statement 
job step, contains load 
modules that may be used 
to the linkage editor, 
contains object modules, 
contain control statemen 
symbols that are undefin 
primary input has been p 
automatic library call m 
the automatic call libra 
will resolve the referen 
NCAL option is specified 
subroutine library must 
the automatic call libra 
subroutines will be need 
external references. Ot 
data sets may be concate 
the following example: 



te members of the 
ure library, and 

also create 
r use in the copy 
all library, and 
it ion, he can 
sets to be used as 

input to the 
an create libraries 

program entries. 



brary, defined by 
in the link-edit 
modules or object 

as secondary input 
If the library 

it may also 
ts. External 
ed after all 
rocessed cause the 
ec nanism to search 
ry for modules that 
ces, unless the 
. The COBOL 
be specified for 
ry if any of the 
ed to resolve 
her partitioned 
nated as shown in 



//SYSLIB DD DSNASE=SYS1.C0BLIB,DISP=SHR 
// DD DSNAME=MYLIB,DISP=SHR 



In this case, both the COBOL subroutine 
library and the partitioned data set named 
MYLIB are available to the automatic 
library call. 
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I //CATALOG 

!// 

J//SYSUT2 

i// 

I// 

f// 

I// 

J//SYSPSINT 

J //SYS IN 

|./ 

I-/ 

I 

I 

1 

1 

I-/ 

I/* 



JOB user information 

EXEC PGM=IEBUPDTE,PARH=(NEI) 
DD DSNAME=COPYLIB,UNIT=3330, 

DISP= (NEW, KEEP) , 
VOLUME=SER=11 111 1 , 
SPACE=(TEK, (15,10,2) ) , 
DCB=(LRECL=80,BLKSIZE=80,RECFH=F) 
DD SYSOUT=A 

DD * 

ADD NAME=CFILEA, LEVEL=00,SOURCE=0,LIST=ALL 

NUMBER NEW1=10,INCR=5 

BLOCK CONTAINS 13 RECORDS 
RECORD CONTAINS 120 CHARACTERS 
LABEL RECORDS ARE STANDARD 
DATA RECORD IS FILE-OUT. 
ENDUP 



Figure 139. Entering Source Statements into the COPY Library 



I //UPDATE 

I// 
J//SYSUT1 

I// 
I// 
I// 

J//SYSUT2 

I// 

i// 

J//SYSPRINT 

I//SYSIN 

L/ 

I 

!-/ 

I/* 

i 



JOB 

EXEC 

DD 



DD 



user information 
PGM=IEBUPDTE,PARH= (HOD) 
DSNAME=COPYLIB,UNIT=3 340, 

DISP= (OLD, KEEP) , 

VOLUME=SER=1 11111, 

DCB= (f?ECFH=F,BLKSIZE=80) 
DSNAME=COPYLIB,UNIT=3340, 

DISP={OLD,KEEP) , 

VOLUME=SER=1 11111 
SYSOUT=A 
* 

CHANGE NAHE=CFILEA,LEVEL=01,SOURCE=0,LIST=ALL 

BLOCK CONTAINS 20 RECORDS 
ENDUP 



DD 
DD 



00000010 



Figure 140. Updating Source Statements in a COPY Library 



H2te: If the partitioned data set named in 
the SYSLIB DD statement contains load 
modules, any data set concatenated with it 
must also be a load module partitioned data 
set. If the first contains object modules, 
the others must also contain object 
modules. 

The linkage editor LIBRARY control 
statement has the effect of concatenating 
any specified member names with the 
automatic call library. 



CO 80 L .,., Co py L ib r ar y 



The COBOL copy library is a user-created 
library consisting of statements or entire 
COBOL programs frequently used by the 



programmer. The programmer can include 
these statements or programs into a program 
at compile time. He calls them with the 
COBOL COPY statement or BASIS card. 

To enter or update source statements in 
the copy library, a utility program must be 
used. IEBUPDTE is the IBM-supplied utility 
program used to catalog procedures. A full 
discussion of the statements used in this 
program may be found in the publication 
OS/VS Utilities . 

Maximum Block Size; 

The maximum block size for the copy 
library is restricted to 16K. 

iMiiiEl.e.jjibraries: if more than one copy 
library is being used, the COPY statement 
must include the phrase IN/OF library-name, 
where library-name is the ddnaae 
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identifying the particular partitioned data 
set to be copied from. (If this qualifying 
phrase is omitted, the default ddname 
becomes SYSLIB or its alternate.) 

gnterinq Source Statem ents : Figure 139 
illustrates the method to insert source 
statements into a copy library member. 



The ./ ADD statement 
statement that copies CF 
library called COPYLIB. 
an FD entry. The NUMBER 
a sequential numbering s 
statements in the librar 
statement is assigned nu 
each succeeding statemen 
5. The entries followin 
statements are the actua 
to be stored. The ENDUP 
the end of the entries t 



is a utility 

ILEA into the 
CFILEA describes 
statement assigns 

ystem to the 

y. The first 

mber 000010 and 

t is incremented by 

g the utility 

1 source statements 
statement signals 

o be inserted. 



The same procedure can be used to store 
entire source programs. 



Up dating Source statements; Figure 140 
illustrates the method to update source 
statements in a copy library member 
inserted in the previous example. 

SYSUT1 and SYSUT2 describe the data 
sets. Note that changes may be made on the 
same data set (identified on the DSNAME 
parameter) . The utility statement CHANGE 
indicates that the ne» entry of CFILEA 
replaces the old entry. Alternatively, the 
UPDATE IN PLACE parameter of the change 
statement could have been used to avoid 
moving the entire member, (CILEA, to the 
first available area in the file. The 
sequence number of the altered statement 
must be supplied. This number, 00000010, 
is indicated in columns 73 through 80 of 
the replacement source statement. Note 
that, although in the insert example {see 
Figure 139 — NU1BES statement) the number 
was coded as 10 without leading zeros, the 
program assigns an 8-character field to a 
sequence number and pads with leading zeros 
if necessary. When updating a sequence 
number in a library, these leading zeros 
must be included. 
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At compile time, COPYLIB is identified 
on a DD statement; for example: 



//SYSLIB DD DSNAME=COPYLIB, X 

// V0LUME=SER=111111, X 

// DISP=SHR,UNIT=2314 



Re trievi ng Source statements: Members of 
the cataloged library can be retrieved 
using the COPY statement or BASIS card. 



CO PY Statement 



The COPY statement permits the 
programmer to include stored source 
statements in any of the four divisions. 
If the programmer wishes to retrieve the 
member, CFILEA, stored in the previous 
examples, he writes the statement: 

FD FILEA COPY CFILEA 



The compiler translates this instruction to 
read: 

FD FILEA 

BLOCK CONTAINS 20 RECORDS 
RECORD CONTAINS 12 CHARACTERS 
LABEL RECORDS ARE STANDARD 
DATA RECORD IS FILE-OUT. 



The statements included in the DOWORK 
procedure will immediately follow the 
paragraph-name, replacing the words COPY 
DO WORK. 

Notes: 

1. The SUPPRESS option of the COPY 
statement will be ignored if LISTER or 
FIPS is requested. 

2. Results may be unpredictable if a 
CURRENCY SIGN IS = is specified (only 
allowed with LANGLVL{1)) and a PICTURE 
character string is part of 
pseudo-text and contains a floating 
currency sign. 

3. In order for the text copied to have a 
D inserted in column 7 (debugging line 
indicator) , the D must appear on the 
first line of the COPY statement 
itself. A copy statement itself can 
never be a debugging line; if it 
contains a D and WITH DEBUGGING mode 
is not specified, the COPY statement 
will nevertheless be processed. 

H, No more than 150 COPY-REPLACING pairs 
may be specified in a source program. 
If this limit is exceeded, message 
IKFI20I is issued by the compiler, 
and COPY statements over the limit 
are ignored. 

BASIS Card 



Note that CFILEA itself does not appear in 
the statement. CFILEA is a name 
ide tifying the entries. It acts as a 
header record but is not itself retrieved. 
The compiler source listing, however, will 
print out the COPY statement as the 
programmer wrote it. 

The COPY statement permits the 
programmer to include previously stored 
source statements into any portion of the 
program. 

Assume a procedure named DOWORK was 
stored with the following statements: 

./ ADD NAHE=DOWORK,LEVEL=00, 

SOURCE=0,LIST=ALL 
./ NUMBER SEQ1=400,INCR=10 

COMPUTE QTY-ON-HAND = 

TOTAL-USED-NUMBER-ON-HAND. 
MOVE-QTY-ON-HAND TO PRINT-AREA. 
-/ ENDUP 



To retrieve the stored member, DOWORK, the 
programmer writes: 

paragraph-name. COPY DOWORK. 



Frequently used source programs, such as 
a payroll program, can be inserted into the 
copy library. The BASIS card brings in an 
entire source program at compile time. 
Calling in a program eliminates the need 
for the programmer to handle a program each 
time he wants to compile it. The 
programmer may, however, alter any 
statement in the source program by 
referring to its COBOL sequence number with 
an INSERT or DELETE statement. The INSERT 
statement will add new source statements 
after the sequence number indicated. The 
DELETE statement will eliminate the 
statements indicated by the sequence 
numbers. The programmer may delete a 
single statement with one sequence number, 
or he may delete more than one statement, 
separating by a hyphen the first and last 
sequence numbers to be deleted. 

Note : The COBOL sequence number is the 
6-diqit number that the programmer assigns 
in columns 1 through 6 of the source cards. 
This sequence number has nothing to do with 
the sequence numbers assigned in simulated 
columns 73 through 80 by the IEBUPDTE 
utility program. The sequence numbers 
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J COBOL 

J Sequence 

I Num bers 

1000730 IF ANNUAL-PAY GREATER THAN 15,000 GO TO PAY-WRITE. 

1000735 IF ANNUAL-PAY GREATER THAN 15,000 - BASE-PAY GO TO LAST-TAX. 

| 000740 TAX-PAYR. COMPOTE TAX-PAY = BASE-PAY * .025 

| 000750 HOVE TAX-PAY TO OUTPUT-TAX, 

J000760 PAY-WRITE. MOVE BASE-PAY TO OUTPUT-BASE. 

J 000770 ADD BASE-PAY TO ANNUAL-PAY. 

i 



i 

J000850 



STOP RUN. 



IEBUPDTEJ 
Sequence | 
Numbers ) 
00000105J 
00000110} 
00000115J 
00000120J 
00000125J 
00000130J 

! 

! 

I 
00000240J 



Figure HI. COBOL Statements to Deduct Old Age Tax 



1 
I 

| BASIS PA 
| DELETE 
|000730 
J000735 
J000740 T 



YSOLL 
00730-000740 

IF ANNUAL-PAY GREATER THAN 17800 GO TO PAY-WRITE. 

IF ANNUAL-PAY GREATER THAN 17800 - BASE-PAY GO TO LAST-TAX. 
AX-PAYB. COMPUTE TAX-PAY = BASE- PAY * .044. 



Figure 142. Programmer Changes to Source Program 



assigned by IEBUPDTE are used to update 
source statements in the copy library. 
Changes made using these numbers are 
intended to be permanent changes. The 
COBOL sequence numbers are used to update 
COBOL source statements at compile time. 
Such changes are in effect for the one run 
only. 

Assume that a company payroll program is 
kept as a source program in the copy 
library. The name of the program is 
PAYROLL. During a particular year, old age 
tax is taken out at a rate of two and a 
half percent each week for all personnel 
until earnings exceed $15,000. The coding 
to accomplish this is shown in Figure 141. 

How, however, due to a change in the old 
age tax laws, tax is to be taken out until 



earnings exceed $17,800 and a new 
percentage is to be placed. The programme! 
can code these changes as shown in Figure 
142. 

The altered program will contain the 
coding shown in Figure 143. 



Note that changes made through use of 
the INSERT and DELETE statements remain in 
effect for the one run only. 

Note: If both the COPY statement and the 
BASIS card are used, the library containing 
the member specified in the BASIS card mu st 
be defined first. The COPY libraries 
concatenated with the BASIS library may be 
defined and referenced in any order (see 
"Appendix I: checklist for Job Control 



1000730 
J000735 
J000740 
J000750 
J000760 
J 000770 
1 

i 
t 

J000850 



TAX-PAYR, 



PAY-WRITE. 



IF ANNUAL-PAY GREATER THAN 17800 GO TO PAY-WRITE. 

IF ANNUAL-PAY GREATER THAN 17800 - BASE-PAY GO TO LAST-TAX. 

COMPUTE TAX-PAY = BASE-PAY * .044. 

HOVE TAX-PAY TO OUTPUT-TAX. 

HOVE BASE-PAY TO OUTPUT-BASE. 

ADD BASE-PAY TO ANNUAL-PAY. 



STOP RUN. 



Figure 143. Changed COBOL Statements to Source COPY Library Statements 
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Procedures") . For a discussion of special 
considerations when using BASIS with 'the 
BATCH option, see "Batch Compilation." 



A library of load modules can be created 
by use of the SYSLMOD DD statement in the 
linkage editor job step, as discussed in 
"Job Library." 



JO B Librar y 



SHARING COBOL LIBRARY SUBROUTINES 



The job library consists of one or more 
partitioned data sets that contain load 
modules to be executed. It is specified by 
the JOBLIB DD statement that must precede 
the EXEC statement of the first step of a 
job. Partitioned data sets assigned to the 
job library are concatenated with the link 
library so that any load module is obtained 
automatically when its name appears in the 
PGM= parameter of the EXEC statement. The 
following statements illustrate how three 
cataloged partitioned data sets can be 
assigned to the job library: 

//MY JOB JOB ... 

//JOBLIB DD DSNAME=MYLIB1,DISP= (OLD, PASS) 

// DD DSNAME=HYLIB2,DISP= (OLD, PASS) 

// DD DSNAHE=MYLIB3,DISP=(0LD,PASS) 

//STEP1 EXEC ... 



Use of the COBOL Library Management 
Feature makes it possible for all programs 
in the same or different regions/partitions 
to share one copy of the COBOL library 
subroutines. That is, the most economical 
use of main storage is made when the most 
freguently used COBOL library subroutines 
are placed in the 0S/VS2 link pack area 
(LPA) , or the 0S/VS1 resident reenterable 
routine (RRR) area, rather than in each 
region/partition. To make the most 
effective use of the Library Management 
Feature, and to use the IBM cataloged 
procedures whether or not Library 
Management is needed, the user should 
concatenate the COBOL subroutine library 
with the system link library, or specify it 
to be used as such a library in the 
appropriate system parameter library 
member. 



//STEP2 EXEC ... 



These statements specify tha 
library containing the data 
HYLIB2, and MYLIB3 is to be 
with the link library. When 
is named in an EXEC statemen 
of the job, the directories 
library will be searched for 
When a job library is specif 
the link library is searched 
load module only when the mo 
found in the job library. 



t the job 
sets MYLIB1, 
concatenated 

a load module 
t in any step 
of the job 

the name, 
ied for a job, 

for a named 
dule is not 



Partitioned data sets used in the job 
library can be created by specifying the 
partitioned data set name and the member 
name in the SYSLMOD DD statement when each 
member is processed by the linkage editor. 



Additional Input to the Linkage, Editor : 
Libraries of object modules (with or 
without linkage editor control statements) 
and libraries of load modules can be used 
as additional input to the linkage editor. 
Members are specified by use of the INCLUDE 
and LIBRARY linkage editor control 
statements. 

A library of object modules and control 
statements can be created by use of the 
IEBUPDTE utility program. 



The user may reguest the COBOL Library 
Management Feature at compile time, via the 
RESIDENT option (see the section "Options 
for the Compiler" in the chapter entitled 
"Job Control Procedures"). 



CONCATENATING THE SUBROUTINE LIBRARY 



To co neat en 
with the link 
the IEBUPDTE u 
member named L 
specifying the 
either the ent 
or a private 1 
user-selected 
Note that the 
subroutines mu 



ate the subroutine library 
library, the user executes 
tility program to add a 
NKLSTOO to SYS1.PARMLIB, 

library desired (that is, 
ire COBOL subroutine library 
ibrary containing 
COBOL library subroutines) . 
library containing the 
st be cataloged. 



An installation that is planning to use 
the Library Management Feature will find it 
convenient to include frequently used COBOL 
library subroutines in the OS/VS2 LPA or 
the 0S/VS1 RRR area. Infreguently used 
subroutines are then brought into the 
region/partition as reguired. To add COBOL 
subroutines to the RRR area, the user 
invokes the IEBUPDTE utility program to add 
a member named IEAIGGXX (see Note 2 in 
Figure 143) to SYS 1.PARMLIB, specifying all 
names and aliases for the COBOL library 
subroutines to be included. Then, at an 
initial program load (IPL) time, the 
operator identifies the link list to the 
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system, which subsequently places the 
identified COBOL subroutines in main 
storage in the RRH area. 

Figure 144 illustrates how an 
installation can accomplish both these 
functions in one operation. The encircled 
letters in the figure refer to the JCL 
suggested A to concatenate the COBOL 
subroutine library (SYS1 .COBLIB) with the 
system link library (SYS1. LINKLIB) , and 
then B to place the user list of desired 
COBOL library subroutines and their aliases 
to the RRR. (For further information, see 
the publication QS/VS COBOL Comp iler and 
Library Inst allation Re feren ce Materi al. ) 



Notes: 

1. If the user does no 
COBOL subroutines i 
need not execute th 
IEBUPDTE utility pr 
IEAIGGXX to SYS 1. PA 
He may still make u 
Management Feature, 
required library su 
loaded into his own 
when they are neede 
programs, and delet 
longer needed. Thu 
subroutines needed 



t wish to place any 
n the RRR area, he 
e portion of the 
ogram that adds 
RMLIB shown above, 
se of the Library 

However, all 
brou tines will be 
region/partition 
d by one or more 
ed when they are no 
s, not all library 
by all programs in 



the region need be resident at the 
same time. In this case, however, the 
user must supply a job control card at 
execution time pointing to the COBOL 
subroutine library or to his own 
private library of COBOL subroutines. 
(For a discussion of the various COBOL 
library subroutines available to the 
programmer, see "Appendix B: COBOL 
Library Subroutines.") 

If one or more programs in a given 
region/partition request the COBOL 
Library Management Feature, then the 
main program and all subprograms in 
that region/partition must use it. 
Otherwise, the multiple copies of 
COBOL library subroutines resident at 
one time may cause unpredictable 
results. 



CRE&TINS AND CHANGING LIBRARIES 



A programmer can create or change a 
partitioned data set in one of three ways: 

(1) through the use of DD statements, 

(2) through the use of utility programs, 
and (3) through the use of certain linkage 
editor control statements. 



//CATLG 


JOB 


// 


EXEC 


//SYSPRINT 


DD 


//SYSUT1 


DD 


//SYS0T2 


DD 


//SYS IN 


DD 


-/ 


REPL 



-/ 



-/ 
/* 



ADD 



ENDUP 



user information 

PGM=IEB0PDTE,PARM=MOD 

SYSOUT=A 

DSN=SYS1.PARMLIB,DISP=SHR 

DSN=SYS1.PARMLIB,DISP=SHR 

* 

NAME=LNKLSTOO,LIST=ALL 

SYS1. LINKLIB, SYS1. COBLIB 

NAME=IEAIGG01 ,LIST=ALL 

SYS 1 962 { 562B 1, NAME 1, ALIAS 1,, 
SYS1. LINKLIB, NAME, ALIAS 



Notes 

1. The name used on the card after the REPL statement must identify the data set 
(SYS1. COBLIB) to be concatenated with the system link library, and is selected by 
the installation. (Note that this data set must be cataloged.) 

2. The last two digits of the member-name specified in the ADD statement can vary, but 
the digits specified here must also be specified in the RAM = parameter used at IPL 
time. For example, if IEAIGG02 were specified, »RAM=02 , would be required at IPL 
time. For 0S/VS2 Release 1, modify the IEAIGG00 member of SYS1.PARMLIB as 
explained in 0S/VS2 Ini tializat io n an d Tuning Guide. GC28-0681. For 0S/VS2 Release 
2 and later, use IEALPOO instead of IEAIGGOO. 

3. The names and aliases of the COBOL library subroutine members to be made resident 
must be specified by the installation in the ADD statement. The system searches 
the last name first; in this case, ALIAS1 is searched last. The user should, 
therefore, specify the most frequently used name last. 

i , 

Figure 144. Concatenating the Subroutine Library 
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The DD statement can be used to create 
libraries as is discussed at the beginning 
of this chapter. In addition, DD 
statements can be used to add members to 
existing libraries, including the link 
library, and to retrieve members of 
existing libraries. 

Utility programs can be used to create 
libraries such as those used in the copy 
library or as secondary input to the 
linkage editor. In addition, utility 
programs can be used to move, copy, and 
replace members of an existing library; to 
add, delete, and renumber the records 



within an existing library; and to assign 
sequence numbers to the records of a new 
library. 



Linkage editor control statements can be 
used to make changes to members of a 
library of load modules. The name of a 
member can be changed or additional names 
can be specified. Additional entry points 
can be identified, existing entry points 
can be deleted, and portions of a load 
module can be deleted or replaced, For 
further information, see the publication 
OS/VS Linkage Editor .and .Loader. 
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PSING THE CATALOGED PROCEDURES 



A catalog 
control stat 
data set cal 
(SYS1.PROCLI 
the library 
EXEC statente 
stream. Fre 
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editing, can 
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be cataloge 
se. 



is a set of job 
d in a partitioned 
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member name in an 
step in the input 

procedures, such 
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process one or more 
the remaining steps 
statements in the in 
use several cataloge 
processing one or mo 
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cataloged procedure 
step. 
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rocessing of an entire 
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steps of a job, with 
defined by job control 
put stream. A job can 
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re of the job steps. A 
r execution of the same 
in more than one job 



This chapter describes the following: 

• How to call cataloged procedures 

• The types of cataloged procedures, 
including those supplied by IBM for use 
with COBOL source programs 

• How to add procedures to the procedure 
library 

• How to modify existing procedures for 
the current job step only 

• How to override and add to cataloged 
procedures 

• How to use the DDNAME parameter in 
cataloged procedures 



procedure COBUC to process the job step 

STEPQ. 

A job step that calls for execution of i 
cataloged procedure can also contain DD 
statements that are applicable to the job 
steps of the cataloged procedure. A job 
that calls for execution of a cataloged 
procedure may, in other steps, call for 
execution of other cataloged procedures, 
call for other executions of the same 
cataloged procedure, or call directly for 
execution of load modules. The following 
example shows a job control procedure that 
calls both cataloged procedures and load 
modules. 



//J0B1 
//STEP A 
//COB. SYSIN 



JOB 

EXEC COBPC 

DD * 



{source module) 



/* 
//STEPL 



EXEC 



PGH=IEWL 



(DD statements for the linkage editor) 



//STEPE 



EXEC PGfi=*. STEPL. SYSLMOD 



(DD statements for user-defined files) 



CALLING CATALOGED PRQCEDPRES 



A cataloged procedure is called by a job 
that appears in the input stream. The job 
must consist of a JOB statement and an EXEC 
statement that specifies the cataloged 
procedure name in the positional parameter 
(either procnaae or PROC=procnaae) . For 
example: 

//STEPQ EXEC COBPC 
//STEPQ EXEC PROC=COBPC 



Either of these EXEC statements could be 
used to call the IBM-supplied cataloged 



The IBM-supplied cataloged procedure 
COBPC for compilation is used to process 
STEPA. The COB. SYSIN DD statement is 
required to define the input to the 
compiler. The remaining statements in the 
procedure refer to execution of the linkage 
editor and the subsequent load module. 



Data Sets Produced by Cataloged Procedures 



Data sets produced during execution of a 
cataloged procedure can be used in 
subsequent job steps. They can also be 
called as follows: 
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//jobname JOB 1234, J. SMITH 

//STEPA EXEC PROCED 

//PROC1.SYSIN DD * 



(source module) 



/* 
//stepnaae 



EXEC PGM=*. STEPA. PROC2.SYSLHOD 



2. A DD statement with JOBLIB in the 
name field 

3. A DD statement with an * in the 
operand field 

<l. A DD statement with DATA in the 
operand field 

5. The delimiter statement 



(DD statements for user- defined files) 



Testing Pr oqramm er-flritten Procedures 



The cataloged procedure PROCED is 
composed of two job steps, PROC1 and PROC2, 
that compile and linkage edit the source 
module. 



A procedure can be tested before it is 
placed in the procedure library by 
converting it into an in-stream procedure 
and executing it any number of times during 
a job. For further information about 
in-stream procedures, refer to the section 
"Testing a Procedure as an In-Stream 
Procedure' 1 . 



TYPES OF CATALOGED PROCEDURES 



The programmer can write his own 
procedures and catalog them, or he can use 
the five COBOL cataloged procedures 
provided by IBM. 



PROGRAMMER -WRITTEN CATALOGED PROCEDURES 



The programmer can write 
procedures, consisting of EX 
statements, which incorporat 
procedures he uses frequentl 
example, the programmer may 
an EXEC statement and the as 
statements for a job step th 
execution of a program. In 
DD statements need not be sp 
time the program is executed 



cataloged 

EC and DD 

e job control 

y. For 

wish to catalog 

sociated DD 

at .specifies 

this way, the 

ecified each 



In writing a procedure for cataloging, 
the programmer must follow these rules: 

* Another cataloged procedure cannot be 
referred to, i.e., only the 
PGM=progname form in an EXEC statement 
can be used. 

Note, however, that a cataloged 
procedure may contain a DD statement 
that refers to a cataloged data set. 

* SYS ABEND or SYSUDUMP DD statements 
should not be cataloged because they 
cannot be overridden. 

* The following statements cannot be used 
in a cataloged procedure: 

1. The JOB statement 



Adding Procedures to the Procedure ..Library 



The IEBUPDTE utility program is used to 
add procedures to the procedure library. A 
description of the use of this program is 
given in the publication OS/VS Utilities. 

In Figure 145, two procedures are added 
to the procedure library (SYS1.PR0CLIB) . 
All control statements are in the input 
strearo. 

The first procedure is for a COBOL 
compilation. Mass storage volumes are 
specified for the four utility data sets, 
and 100 tracks are allocated for each 
utility data set. This cataloged procedure 
is named COBDA. 

The second procedure is also for a COBOL 
compilation. Unlabeled tape volumes are 
specified for three utility data sets; for 
the fourth, SYSUT1, a mass storage device 
must be specified. This cataloged 
procedure is named COBTP. 

Job control statements: the EXEC card 
specifies that the IEBUPDTE program is to 
be executed, and PARM=NE8 is used because 
all data is read from one source, i.e., the 
input stream. 

Utility statements: the ADD statement 
specifies the member name of the procedure, 
the level modification (00, first run) and 
the source of the modification (0, 
user-supplied) . The NUMBER statement 
specifies the sequence numbers for records 
in the member. The first record of the 
cataloged procedure is numbered 00000010, 
and subsequent records are incremented by 
tens. 
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J Job 


//ADPROC 


JOB 


jcontrol 


//STEP1 


EXEC 


} Language 


//SYSPRINT 


DD 


J Statements 


//SYSUT2 


DD 




//sysin 


DD 


i Utility 


-/ 


ADD 


J Statements 


-/ 


NUMBER 




//COB 


EXEC 




//SYSUT1 


DD 




//SYSUT2 


DD 


| First 


//SYSUT3 


DD 


| Procedure 


//SYSDT4 


DD 




//SYSPRINT 


DD 




//SYSPUNCH 


DD 


{Utility 


-/ 


ADD 


J Statements 


-/ 


NUMBER 




//COB 


EXEC 




//SYSUT1 


DD 


i Second 


//SYSUT2 


DD 


| Procedure 


//SYSUT3 


DD 




//SYSUT4 


DD 




//SYS PRINT 


DD 




//SYSPUNCH 


DD 


f Delimiter 


./ 


ENDUP 


\ Statements 

t 


/* 




Figure 145. 


Example of Adding P 



1234,J.DUB0B 

PGM=IEBUPDTE,PARM=NES 
SYSOUT=A 

DSNAME=SYS1.PRGCLIB,DISP=0LD 
DATA 

NAME=COBDA,LEVEL=00,SGURCE=0 
NES1 =00000010, I NCR=000000 10 

PGS=IKFCBL00 

UNIT=SYSDA,SPACE= (TRK, (100,10) ) 

UNIT=SYSDA,SPACE= {TRK, (100, 10) ) 

UNIT=SYSDA,SPACE=(TRK, (100,10) ) 

UNIT=SYSDA,SPACE= (TRK, (100,10) ) 

SYSO0T=A 

SYSOUT=B 

N AME=COBTP , LE VEL=00 , SO0SCE=0 
NEW 1=10, INCR=10 

PGM=IKFCBL00 

UNIT=SYSDA,SPACE= (TRK, (100, 10) ) 

UNIT=2400,LABEL=(,NL) 

UNIT=2400,LABEL=(,NL) 

UNIT=2400,LABEL=(,NL) 

SYSOUT=A 

SYSOUT=B 



Note that leading zeros in the NUMBER 
statement are not necessary, as indicated 
in the exaople for the COBTP procedure. 



IBM-SUPPLIED CATALOGED PROCEDURES 



These procedures may be used with any of 
the job schedulers released as part of the 
IBM Operating System. When parameters 
required by a particular scheduler are 
encountered by another scheduler that does 
not require those parameters, either they 
are ignored or alternative parameters are 
substituted automatically. 



IBM distributes cataloged procedures 
with the program product, which can be 
incorporated when the system is generated. 



Five of the procedures are for use with 
COBOL programs. 

1. COBUC provides for compilation. 

2. COBUCL provides coapilation and 
linkage editing. 

3. COBULG provides linkage editing and 
execution. 

4. COBDCLG provides for compilation, 
linkage editing, and execution. 

5. COBUCG provides for compilation and 
loading. 



The five cataloged procedures are shown 
in Figures 146 through 150. (Space 
allocations in these procedures are in 
terms of record lengths on the 2314 disk 
storage device.) Note that when DSNAME=SS 
is used in a DD statement the specified 
data set is given a unique name by the 
operating system, and it is assumed to be a 
temporary data set that will be deleted 
when the job is completed. If the data set- 
is to be kept, the DD statement can be 
overridden with a permanent data set name, 
and the appropriate parameters can be 
specified. 

fi.2iS* If tfte compiler options are not 
explicitly supplied with the procedure, 
default options established at the 
installation apply. The programmer can 
override these default options by using an 
EXEC statement that includes the desired 
options (see "overriding and Adding to 
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EXECStatements" and "Overriding Cataloged 
Procedures Using Symbolic Parameters") . 



£E2£J§<lur e_ fi§t ming Conventions 



Procedure names begin with the 
abbreviated name of the processor program, 
which, in the case of the COBOL procedures, 
is COB. 



Data set Names in Procedures 



When DSNAME=&&name is used in a DD 
statement, the specified data set is given 
a unique name by the scheduler, and it is 
assumed to be a temporary data set that 
will be deleted when the job terminates. 
If the data set is to be retained, the DD 
statement must be overridden with a 
permanent data set name and appropriate 
DISP parameters. 



The processor's abb 
followed by the proces 
(0) and then by C {com 
edit), G (go -- i.e., 
combinations of them. 
COBUC is a single-step 
compiles a program usi 
processor; COBUCLG is 
wherein the first step 
using COBOL, the secon 
output of the first st 
step executes the outp 
editor. 



reviated name is 
sor's level indicator 
pile), L (linkage 
execute) , or 

Hence, procedure 

procedure that 
ng the COBOL 
a 3-step procedure 

compiles a program 
d step link-edits the 
ep, and the third 
ut of the linkage 



Step Names in Procedures 



In a cataloged procedure, the step name 
is the same as the abbreviated processor 
name (LKED) . The step that executes a 
compiled and link-edited program is named 
GO. 

For example, in the procedure named 
COBUCLG, the first step is named COB, the 
second step is named LKED, and the third 
step is named GO. 



Unit Names in Procedures 



The two unit names used in IBM-supplied 
cataloged procedures are as follows: 

SYSSQ any magnetic tape or mass 
storage device 

SYSDA any mass storage device 



A pool of units must 
these unit names during 
generation procedure. F 
23 14 Disk Storage Drives 
to the SYSSQ name. Then 
Magnetic Tape Units and 
Drives might be assigned 
Once a pool of devices i 
classes, device select io 
Job Scheduler. 



be assigned to 

the system 

or example, only 
might be assigned 
again, both 2400 

2314 Disk Storage 
to the SYSSQ name. 

s assigned to these 

n is done by the 



CO BUC Proc e dux. e 



The COBUC procedure is a single-step 
procedure to execute the COBOL compiler. 
It produces a punched object deck. Figure 
145 shows the statements that make up the 
COBUC cataloged procedure. 

The following DD statement must be 
supplied in the input stream: 



//COB.SYSIN DD * 



(or appropriate 
parameters defining an 
input data set) 



Optionally, the delimiter statement (/*) 
may follow the source module. 



COBUCL Procedure 



The COBUCL procedure is a two-step 
procedure to compile and link-edit using 
the COBOL compiler. Figure 146 shows the 
statements that make up the cataloged 
procedure. 

The COB job step produces an object 
module that is input to the linkage editor. 
Other object modules may be added as 
illustrated in Example 5 under "Using the 
DDNAME Parameter." 

The following DD statement, indicating 
the location of the source module, must be 
supplied in the input stream: 



//COB.SYSIN DD * 



COBULG Procedure 



(or appropriate 
parameters) 



The COBULG cataloged procedure is a 
two-step procedure to link-edit and execute 
the output of a COBOL compilation. Figure 
148 shows the statements that make up the 
procedure. 
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The following DD statement indicating 
the location of the object module must be 
supplied in the input stream: 



//LKED. SYSIN DD * 



(or appropriate 
parameters) 



If the COBOL program refers to SYSIN in 
the execution step, the following DD 



statement must also be supplied in the 
input stream. 



//GO. SYSIN DD * 



(or appropriate 
parameters) 



If the COBOL program refers to other 
data sets in the execution step such as 
user-defined files, DD statements that 
define these data sets must also be 
provided. 



1//C0B EXEC PGM=IKFCBL00,PA8M = , DECK,NOLOAD,SUPMAP« ,REGI0N=128K 

I//SYSPEINT DD SYS0UT=A 

J//SYSPUNCH DD SYSOUT=B 

J//SYSUT1 DD UNIT=SYSDA,SPACE= (460, (700,100)) 

J//SYSUT2 DD ONIT=SYSDA,SPACE= (460, (700,100)) 

I//SYSUT3 DD UNIT=SYSDA,SPACE=(460, (700,100)) 

I//SYSDT4 DD UNIT=SYSDA,SPACE= (460, (700, 100) ) 

i , 



Figure 146. Statements in the COBUC Procedure 



\ //COB 

J//SYSPBINT 

I//SYSUT1 

I//SYSUT2 

I//SYSUT3 

J//SYSUT4 

J//SYSLIN 

I// 
I//LKED 

!// 
I//SYSLIN 

I// 

J//SYSL30D 

I// 

i //SYS LIB 

I //sys or 1 
I// 

I//SYSP8INT 

t 



EXEC PG«=IK 
DD SYSO0T=A 
DD 0NIT=SYS 
DD UNIT=SYS 
DD UNIT=SYS 
DD UNIT=SYS 
DD DSNAHE=S 

SPACE= 
EXEC PGM=IE 

REGION 
DD DSNAME=S 
DD DDNAME=S 
DD DSNAME=S 

SPACE= 
DD DSNAME=S 
DD UNIT = (SY 

SPACE= 
DD SYSOUT=A 



FCBL00,EEGION=128K 

DA,SPACE= (460, (700,100) ) 

DA,SPACE=(460, (700,100)) 

DA,SPACE= (460, (700, 100) ) 

DA,SPAC1=(460, (700,100) ) 

SLOADSET,DISP=(MOD,PASS) ,0NIT=SYSDA, 

(8 0, (500,100)) 

WL,PABM=»LIST,XEEF,LET«,COND=(5,LT,COB) , 

=96K 

SLOADSET,DISP= (OLD, DELETE) 

YSIN 

SGOSET,DISP= (NEW, PASS) ,UNIT=SYSDA, 

(1024,(50,20,1)) 

YS1.COBLIB,DISP=SHR 

SDA, SEP= (SYSLIN,SYSLSOD) ) , 

(1024, (50,20)) 



Figure 147. Statements in the COBOC.L Procedure 



J//LKED EXEC PGM=IEWL,PARH=»LIST, XBEF,LET* , BEGION=1 28K 

I//SYSLIN DD DDNAHE=SYSIN 

J//SYSLMOD DD DSNAME=&£GOSET (GO) ,DISP= (NEW ,PASS) ,0NIT=SYSD A, 

J// SPACE=(1024, (50,20,1)) 

I//SYSLIB DD DSNAHE=SYS1.C0BLIB,DISP=SHE 

J//SYSOT1 DD 0NIT=(SYSDA, SEP=(SYSLIN,SYSLHQD) ) , 

|// SPACE= (1024, (50,20) ) 

I//SYSPRINT DD SYS00T=A 

I//GO EXEC PGH=*.LKED.SYSLMOD,COND= (5,LT,LKED) 

i 



Figure 148. Statements in the COBOLG Procedure 
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I//COB EXEC PGH=IKFCBL00,PAEM=SUPflAP,REGION=128K 

I//SYSPRINT DD SYSOUT=A 

I//SYSUT1 DD UNIT=SYSDA,SPACE= (460, (700, 100) ) 

I//SYSUT2 DD UNIT=SYSDA,SPACE=(460, (700,100)) 

1//SYSUT3 DD UNIT=SYSDA,SPACE= (460, (700,100)) 

I//SYSUT4 DD UNIT=SYSDA,SPACE= (460, (700,100)) 

1//SYSLIH DD DSNAME=&&LOADSET,DISP=(HOD,PASS) ,UNIT=SYSDA, 

!// SPACE= {80, (500,100)) 

I//LKED EXEC PG^IEWL^PARH^LIST^REF^ET* ,COND= (5, LT,COB) , 

J// REGION=96K 

I//SYSLIN DD DSNAME=S&LOADSET,DISP= (OLD, DELETE) 

1// DD DDNAME=SYSIN 

J//SYSLHOD DD DSNAHE=ft&GOSET (GO) , DISP= (NE» ,PASS) ,ONIT=SYSDA, 

I// SPACE= (1024, (50,20,1)) 

1//SYSLIB DD DSNAME=SYS1.COBLIB,DISP=SHR 

I//SYS0T1 DD UHIT=(SYSDA,SEP=<SYSLIN,SYSLHOD) ) , 

|// SPACE= (1024, (50,20)) 

I//SYSPEINT DD SYSOUT=A 

J//GO EXEC PGM=*.LKED.SYSLaOD,COHD=(<5,LT,COB) , (5,LT,LRED)) 

c , 



Figure 149. Statements in the COBUCLG Procedure 



J//COB EXEC PGM=IKFCBL00,PARM=«LOAD» ,SEGION=128K 

J//SYSPSINT DD SYSO0T=A 

I//SYS0T1 DD UNIT=SYSDA,SPACE= (460, (700,100) ) 

I//SXS0T2 DD UNIT=SYSDA,SPACE=(460, (700,100)) 

J//SYS0T3 DD UNIT=SYSDA,SPACE= (460, (700,100) ) 

J//SYSUT4 DD UNIT=SYSDA,SPACE={460, (700,100) ) 

J//SYSLIN DD DSNAME=&&LOADSET,DlSP=(HOD,PASS) , 

J// UNIT=SYSDA,SPACE= (80, (500, 100) ) 

I//GO EXEC PGM=LOADER,PARM=»MAP,LET»,CQND=(5,LT,COB) ,REGION=106K 

I//SYSLIN DD DSNAME=*. COB. SYSLIN,DISP=(OLD, DELETE) 

I//SYSLOUT DD SYSOUT=A 

1//SYSLIB DD DSNAME=SYS1.COBLIB,DISP=SHR 

t ,„ . 



Figure 150. Statements in the COBUCG Procedure 



COBOCLG Procedure 



location of the input data set must also be 
supplied: 



The COBOCLG procedure is a three-step 
procedure to compile, link-edit, and 
execute using the COBOL compiler. Figure 
149 shows the stateaents that make up the 
procedure. 

The COB job step produces an object 
module that is input to the linkage editor, 
Other object modules may be added as 
illustrated in Example 5 under "Using the 
DDHAHE Parameter." 

The following DS statement, indicating 
the location of the source module, must be 
supplied in the input stream: 



//COB.SYSIN DD 



* (or appropriate 
parameters) 



If the COBOL program refers to SYSIH, 
the following DD statement indicating the 



//GO. SYSIN DD 



* (or appropriate 
parameters) 



If the COBOL program refers to other 
data sets, DD statements that define these 
data sets must also be supplied, 



COBOCG Procedure 



The COBUCG procedure is a two-step 
procedure to compile, load, and execute 
using the COBOL compiler and OS loader. 
Figure 150 shows the statements that make 
up the procedure. 

The COB job step produces an object 
module that is input to the loader. 



Using the Cataloged Procedures 361 



The following DD statement, indicating 
the location of the source nodule, aust be 
supplied in the input stream: 



//COB.SYSIN DD 



* (or appropriate 
parameters) 



If the COBOL program refers to SYSIN, 
the following DD statement indicating the 
location of the input data set aust also be 
supplied: 



//GO. SYSIN DD 



* {or appropriate 
parameters) 



If the COBOL program refers to other 
data sets, the DD statements that define 
these data sets must also be supplied. 



MODIFYING, EXISTING CATALOGED PROCEDURES 



Existing cataloged procedures can be 
permanently modified by using the IEBDPDTE 
utility program described in the 
publication OS/VS tit ill ties. 



2. 



a cataloged procedure step is to be 
tested, the name of the step in the 
procedure (procstep) must be qualified 
by the name of the step that called 
for execution of the cataloged 
procedure (stepnaae) . 

Specify in the operand field of the 
EXEC statement calling the procedure 
only the keyword parameters and 
subparameters, for example: 



COND= (subparameters) 



If a multiste 
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the exception 
steps in the 
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li2£:§: A parameter in an EXEC statement 
cannot be partly overridden; it must be 
overridden in its entirety. Any parameter 
not overridden remains as originally 
defined. 



OyERRipiNG AND ADDING TO, CATALOGED 
PROCEDURES 



Any parameter in a cataloged procedure 
except the PGM=progname parameter in the 
EXEC statement can be overridden. 
Parameters or statements not specified in 
the procedure can also be added. When a 
cataloged procedure is overridden or added 
to, the changes apply only during one 
execution. 



OVERRIDING AND ADDING TO EXEC STATEMENTS 

An EXEC statement can be overridden or 
added to in one of two ways: 

1. Specify, in the operand field of the 
EXEC statement calling the procedure, 
the keyword, the procedure step-name 
and the subparameters, for example: 

COND. procstep= (subparameters) 

If a multistep procedure is being 
modified, parameters in the calling 
EXEC statement must be specified step 
by step; i.e. , the parameters for one 
step must be specified before those of 
the next step. If the return code of 



Exampl es o f O verr iding and Adding, to .EXEC 
Statements 



This section contains examples of 
overriding and adding to the EXEC 
statement. The procedures overridden or 
added to are the IBM procedures shown in 
Figures 146 through 150. 

Example 1: The following example shows the 
overriding of one parameter in the EXEC 
statement of the one procedure step in the 
IBM-supplied COBOC procedure. The 
statements appear in the input stream as 
follows: 



//jobname JOB 123*1, J. SMITH 

//STEPA EXEC COBUC, PARS. COB=« DECK, 

// NOLOAD,BOF=4Q00, 

// SIZE=9600« 

//COB. SYSIN DD * 



(source module) 



/< 



Note: In actual use the PARM. COB parameter 
cannot be continued in this manner. In the 
PARM parameter that is overridden, the DECK 
and NOLOAD options were specified. They 
are included again since the parameter must 
be overridden in its entirety. The 
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information is here enclosed in single 
quotation marks, since subpararaeters that 
contain equal signs aust be enclosed in 
this manner. 



Note that all overriding parameters for 
one step of the procedure must be specified 
before those for the next step. 



Example 2: The following example shows the 
overriding of two parameters and the adding 
of another in the EXEC statement of one 
procedure step of the IBM-supplied COBUCLG 
procedure. The statements appear in the 
input stream as shown; 

//jobname JOB 1234, J .SMITH 

//STEPA EXEC COBUCLG, PARM. LKED= 

// (MAP, LIST) ,ACCT=(1234) , 

// C0ND.LKED=(9,LT, 

// STEPA. COB) 

//COB.SYSIN DD * 

(source module) 



Bl.aifile_.4: The following example shows the 
overriding of parameters on all EXEC 
statements in the IBM-supplied COBUCLG 
procedure. The statements appear in the 
input stream as shown: 
//jobname JOB 1234, J. SMITH 

COBUCLG, X 

PARM= (LOAD,P«AP) , X 

C0ND=(3,LT), X 

ACCT= { 1 2 3456, DEPTQ) 



(source module) 





//stepname EXEC 




// 


X 


// 


X 


// 


X 


//COB. SYSIN DD 



/* 



Note: In actual use the COND. LKED and 
PARM. LKED parameters cannot be continued in 
this manner. For the linkage editor job 
step in the above example, the COND and 
PARM parameters have been overridden and 
the ACCT parameter added. 



The PARM options are added to the procedure 
step COB and nullify the PARM options in 
the LKED and GO steps. The COND and ACCT 
parameters apply to all steps in the 
procedure. 



Example 3: The following example shows the 
overriding of individual parameters in more 
than one procedure step of the IBM-supplied 
COBUCLG procedure. The statements appear 
in the input stream as shown. 

//jobname JOB 1234, J. SMITH 

//stepname EXEC COBUCLG,PARM.LKED=Q¥LY, X 

// C0ND.G0={(5,EQ, X 

// stepname. COB) , X 

// (5, EQ, stepname. LKED) ) 

//COB.SYSIN DD * 

(source module) 



/* 

Note: In actual use the COND. GO statement 
cannot be continued in this manner. The 
PARM option CVLY replaces the PARM 
subparaaeters of the link-edit job step. 
The COND option EQ (equal to) replaces the 
option LT (less than) in the execution job 
step. 



TESTING A PROCEDURE AS AN IN-STREAM 
PROCEDURE 



A procedure can be tested before it is 
placed in the procedure library by 
converting it into an in-stream procedure 
and executing it any number of times during 
a job, In-stream procedures are described 
in detail in the publication OS/VS J CL 
Services. 



An in-stream procedure is a series of 
job control language statements enclosed 
within a PROC statement and a PEND 
statement. The following example sbows how 
to convert the COBUC procedure (Figure 146) 
into an in-stream procedure and execute it 
twice. (Remember that in actual use the 
parameters cannot be continued in this 
manner.) 
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//CONVERT 


JOB 


1234, YOUR NAME 




//INSTREAM 


PSOC 






//COB 


EXEC 


PGM=IKFCBLQO,PARM='DECK, 


X 






NQLOAD, SUPHAP», 


X 






REGION=128K 




//SYSPRINT 


DD 


SYSOUT=A 




//SYSPUNCH 


DD 


SYSOOT=B 




//SYSUT1 


DD 


DSNAME=&SSYSUT1, 


X 


// 




UNIT=SYSDA, 


X 


// 




SPACE={460, 6700,100) ) 




//SYSUT2 


DD 


DSNAME=&&SYSU*T2, 


X 


// 




UNIT=SYSDA, 


X 


// 




SPACE=(460, 6700, 100) ) 




//5YS0T3 


DD 


DSNAME=&eSYS0T3, 


X 


// 




ONIT=SYSDA, 


X 


// 




SPACE= (460,6700, 100) ) 




//SYSUT4 


DD 


DSNAME=S&SYSUT4, 


X 


// 




ONIT=SYSDA, 


X 


// 




SPACE=(460,6700, 100) ) 




//ENDPROC 


PEND 






// 


EXEC 


INSTREAM 




//COB. SYSIN 


DD 


* 





parameters, individual sub para meters 
may fee overridden. 

To nullify a keyword parameter (except 
the DCB and AMP parameters) , write, in 
the overriding DD statement, the 
keyword and an equal sign followed by a 
comma. For example, to nullify the use 
of the UNIT parameter, specify UNIT=, 
in the overriding DD statement. 

A parameter can be nullified by 
specifying a mutually exclusive 
parameter. For example, the SPACE 
parameter can be nullified by 
specifying the SPLIT parameter in the 
overriding DD statement. 

The DUMMY parameter can be nullified by 
omitting it and specifying the DSNAME 
parameter in the overriding DD 
statement. 



{input data) 

/* 

// EXEC INSTREAM 

//COB. SYSIN DD * 

(input data) 
/* 



OVERRIDING AND ADDING TO DD STATEMENTS 



To override DD statements in a 
concatenation of data sets, the 
programmer must provide one DD 
statement for each data set in the 
concatenation. Only the first DD 
statement in the concatenation should 
be named. However, if a DD statement 
to be changed follows one (or more) DD 
statement (s) to be left intact, the 
first overriding statement (s) should 
have a blank operand. 



A DD statement can be overridden or 
added to by using a DD statement whose name 
is composed of the procedure step-name that 
qualifies the ddnarae of the DD statement 
being overridden, as follows: 



If the DDNAME=ddnarae parameter is 
specified in a cataloged procedure, it 
cannot be overridden; rather it can 
refer to a DD statement supplied at the 
time of execution. 



//procstep.ddname DD 



(appropriate 
parameters) 



Entire DD statements can also be added. 



Examples of Overriding and Adding to DP 
Statements 



There are rules that must be followed 
when overriding or adding a DD statement 
within a step in a procedure. 

• Overriding DD statements must be in the 
same order in the input stream as they 
are in the cataloged procedure. 

* DD statements to be added must follow 
overriding DD statements. 



There are some special cases that should 
be kept in mind when overriding a DD 
statement. 

* All parameters are overridden in their 
entirety, except for the DCB and AMP 
parameters. Within the DCB and AMP 



This section contains examples of 
overriding and adding to parameters in DD 
statements. The procedures overridden or 
added to are the IBS procedures shown in 
Figures 146 through 150. 

The DDNAME parameter is not used in 
these examples, although it can be useful 
with the cataloged procedures. The use of 
the DDNAME parameter is described in detail 
later in this chapter. 

Example 1; The following example shows the 
overriding of DD statements in the 
IBH-supplied COBOCLG procedure. 



//jobnaae 
//stepname 
//COB.SYSLIN 
//COB. SYSIN 



JOB 1234, J. SMITH 
EXEC COBDCLG 
DD DSNAME=GOFILE 
DD * 
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(source module) 



/* 

//LKED. SYSLIN 

// 



DD DSNAHE=*. COB. SYSLIN, 
DlSP=(OLD,CATLG) 



/* 



(other DD statements for 
user-defined files) 



/* 

The name of the data set in SYSLIH in the 
procedure step COB is changed to GQFILE. 
The name of the data set of SYSLIN in the 
procedure step LKED is changed to a 
reference to the SYSLIN DD statement in the 
COB procedure step, and the data set name 
GOFILE is cataloged. 



Example 2: The following example shows the 
adding of DD statements to the IBM-supplied 
| COBUCLG procedure. 

//jobname JOB 1234, J.SMITH 

//stepname EXEC COBUCLG, X 

// PAEM.COB= (DECK, LOAD, PHAP) 

//COB.SYSPUNCH DD SYSOUT=B 

//COB. SY SIN DD * 



(source module) 



/* 

//GO. TRANSACT 



DD DSNAME=JUNE,DISP=GLD 



in the procedure and must precede those 
statements being added. 



//jobname 

//stepname 

//COB.SYS0T2 

//COB. SYSLIN 

// 

// 

//COB. SYSIN 



JOB 1234, J. SMITH 

EXEC COBUC,PftRM.COB=(LOAD) 

DD SPACF,= ,UNIT=SYSSQ 

DD DSNAME=&&GOFILE, X 

DISP= (MOD, PASS) , X 

UNIT=SYSSQ 
DD * 



/* 



(source module) 



(subsequent job steps) 



The device class on the COB.SYSDT2 DD 
statement is changed to SYSSQ, and the 
SPACE parameter is nullified. Therefore, 
mass storage devices cannot be allocated. 
Any tape volumes to be assigned must have 
standard labels. The COB. SYSLIN DD 
statement is changed so that it passes the 
object module to subsequent job steps. 



Example 4: The following example shows how 
to concatenate a data set with a data set 
defined in the COBULG procedure. 



//jobname 
//stepname 



JOB 

EXEC 



1234, J.SMITH 
COBULG 



(other DD statements for 
user-defined files) 



//LKED.SYSLIB DD 
// DD 



[blank operand field] 
[ parameters ] 



Note: In the foregoing example TRANSACT is 
a cataloged data set. Rhen a data set is 
cataloged, it is sufficient to refer to it 
by DSNAME and DISP=OLD. 

The PARK. COB option DECK and the SYS PUNCH 
DD statement are added to obtain a punched 
object module. The PAHM option PMAP is 
added to obtain a listing of the assembler 
language expansion of the source module. 



Exampl e 3 ; The following example shows 
overriding and adding to DD statements at 
the same time in the IBM-supplied COBUC 
procedure. Note that overriding statements 
must be in the same sequence as they appear 



/* 



Instead of the blank operand field, 
parameters could have been used to override 
the SYSLIB statement; the data set defined 
by the unnamed DD statement would then be 
concatenated to the data set that was 
redefined by overriding. 

Note that a number of libraries could be 
concatenated to the SYSLIB data set. For 
example: 



//LKED.SYSLIB DD 
// DD 

// DD 



DSNAME=USEELIB, DISP=OLD 
DSNAME=MYLIB-DISP=OLD 
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USING. THE DDNAME PARAMETER 



The DDNAM 
dummy data s 
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is used to define a 

assume the 

tual data set, 

DD statement within 

DD statement is 
cs, with the 

replace those of 
DDNAME parameter, 
nt is not found 
a set defined by 
ains a dummy. 



When using the DDNAME parameter, the 
programmer should also keep the following 
in mind: 

• The name of the DD statement referred 
to does not replace the name of the 
referencing statement. 

• If a statement that contains the DDNAME 
parameter is overridden, it is 
nullified. 

• If overriding is performed with a 
statement that contains the DDNAME 
parameter, all parameters in the 
overridden statement are nullified. 



This section contains examples showing 
the use of the DDNAME parameter with 
cataloged procedures. 



The rules for using the DDNAME parameter 
are as follows: 



A backward reference <e. g. , *.ddnaae) 
to a DD statement referred to by a 
DDNAME parameter cannot be used because 
the statement that is referred to loses 
its identity. 



The following DD statements: 



//S1 
//D1 
//D2 
//D3 



EXEC PGM=prognaroe 

DD DDNAME=D3 

DD (parameters X,Y,Z) 

DD {parameters U,T,V) 



will result in the same data definition 
produced by the following statements: 



//S1 
//D1 
//D2 



EXEC PGM=progname 

DD (parameters U,T,V) 

DD (parameters X,Y,Z) 



* A backward refer 
containing a DDN 
used, but only a 
which the DDNAME 
been encountered 
reference is use 
set (defined by 
real characteris 
acteristics will 
the DD statement 
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• Unnamed DD statements can be placed 
after a statement containing the DDNAME 
parameter (indicating concatenation) , 
but unnamed DD statements cannot be 
placed after a statement referred to by 
a DDNAME parameter. 

• The DDNAME parameter can be used a 
maximum of five times in a step, but 
each DDNAME parameter must refer to a 
different statement. 

• The DDNAME parameter cannot be used in 
a JOBLIB statement. 



EXAMPLES OF USING THE DDNAME PARAMETEH 



Example 1: The following example shows how 
to override the first DD statement in a 
cataloged procedure with a DD * statement, 
and allow subsequent statements to be proc- 
essed. The cataloged procedure (PS0C3) is 
as follows: 

//STEP1 EXEC PGM=progname 
//DD1 DD (any parameters) 
//DD2 DD (any parameters) 



The job procedure in which the overriding 
takes place appears in the input stream as 
follows: 



//J0B1 JOB 1234, J. SMITH 

//S1 EXEC PR0C3 

//STEP1.DD1 DD DDNAME=D1 

//D1 DD * 



The STEP1.DD1 statement overrides the 
DD1 statement; the DD2 statement is proc- 
essed; then the D1 statement is processed. 



• The DDNAME parameter is not to be used 
to refer to a DD statement with the 
DYNAM parameter specified. 



Example 2: The following example shows how 
to override the first DD statement in a 
cataloged procedure with a DD * statement 
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and how to add a DD statement- The 
cataloged procedure (PR0C3) is as follows: 

//STEP1 EXEC PGM=progname 

//DD1 DD (any parameters except 

DATA or *) v 
//DD2 DD (any parameters except 

DATA or *) 

The job procedure in which the overriding 
takes place appears in the input stream as 
follows: 

//JOB2 JOB 1234, J. SMITH 

//S1 EXEC PH0C3 

//STEP1.DD1 DD DDNAME=DD4 
//STEP1.DD3 DD (any parameters except 

DATA or *) 
//DD4 DD * 

The DD4 statement effectively overrides 
the DD1 statement, after the DD2 statement 
has been processed and the DD3 statement 
has been added. 



Example 3: The following example shows how 
to concatenate a data set in the input 
stream with a data set defined by a DD 
statement in a cataloged procedure. The 
cataloged procedure (PR0C3) is as follows: 



//STEP1 EXEC PGM=progname 

//DD1 DD (any parameters except 

DATA or *) 
//DD2 DD (any parameters except 

DATA or *) 



The job procedure in which the 
concatenation takes place appears in the 
input stream as follows: 

//JOB3 JOB 1234, J. SMITH 

//S1 EXEC PSOC3 

//STEP1.DD1 DD (blank operand field) 

// DD DDNAME=DD3 

//DD3 DD * 



The data set in the input stream is 
concatenated with the data set defined by 
the DD1 statement after the DD2 statement 
has been processed. 



Example 4 : The following example shows how 
to concatenate a data set in the input 
stream with a data set defined by a DD 
statement in a cataloged procedure and how 
to add a DD statement. The cataloged 
procedure (PE0C3) is as follows: 

//STEP1 EXEC PGM=progname 

//DD1 DD (any parameters except 



DATA or *) 
//DD2 DD (any parameters except 
DATA or *) 



The job procedure in which the concate- 
nation takes place appears in the input 
stream as follows: 



//J0B4 JOB 1234, J.SMITH 
//S1 EXEC PS0C3 



//STEP1.DD2 DD 



// 



DD 



//STEP1.DD3 DD 
//DD4 DD 



(blank operand field) 
DDNAME=DD4 

(any parameters except 
DATA or *) 
* 



Example 5 ; The following example shows how 
the statement DD DDNAME=SYSIN in the 
IBM-supplied COBUCLG procedure can be used 
to add more object modules as input to the 
linkage editor. The statements appear in 
the input stream as follows: 



//jobname 
//step name 



JOB 1234, J. SMITH 
EXEC COBUCLG 



//COB. SYSIN DD * 
(source deck) 

/* 

//LKED. SYSIN DD * 

(first object module) 

(last object module) 

/* 

(//GO. cards) 

The COBUCLG procedure contains the 
following two statements in the linkage 
edit step: 

//SYSLIN DD DSNAME=6SL0ADSET, X 

// DISP= (OLD, DELETE) 

// DD DDNAME=SYSIN 

The result of concatenating SYSIN with 
SYSLIN is that when SYSLIN (input to 
linkage editor) is read, SYSIN is also read 
and linked with it. For example, if 
ILBODSPO is one of the object modules in 
the SYSIN stream, it will be linked with 
SYSLIN. The ILBODSPO module from 
SYS1.C0BLIB will not be used. 
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USING, THE SORT/MERGE FEATURE 



To use the Sort/Merge feature of the 
OS/VS COEOL Compiler, sort/merge feature 
statements are written in the COBOL source 
program. These statements are described in 
the publication IBM VS COBOL for OS/VS, 
The Sort/Merge program itself is described 
in the appropriate Sort /Merq e Programmer's 
Guide. 



of the system-name in an ASSIGN clause in 
the COBOL source program. When the GIVING 
option is specified, the compiler generates 
an output procedure that will open the data 
set, return the records, write the records, 
and close the data set. 



Use of the full COBOL Sor 
requires the program product. 
Sort/Merge, 5740-SM1. The 
5734-SM1, may only be used i 
alone is used — without alter 
sequence and without merge, 
is used, it may issue messag 
"INVALID EXEC OR ATTACH PARA 
will have no effect on opera 
be safely ignored.) 



t/Merge feature 

OS/VS 
S Sort/Merge, 
f COBOL sort 
nate collating 

{If 573 4-SM1 
e IGH067I, 
METER." This 
tions, and may 



DD statements must be written in the 
execution-time job steps of the procedure 
to describe the data sets used by the 
sort/merge program. DD statements for data 
sets used during the sort/merge process are 
described below. 

Note: The Sort/Merge Checkpoint Restart 
feature is available to the programmer 
through the use of the RERUN statement. 



SORT/MERGE DD STATEMENTS 



Three types of data sets can be defined 
for the sort program in the execution time 
job step: input, output, and work. In 
addition, data sets must be defined for 
the use of the system during the sorting 
^operation. 
For MERGE, work DD statements are required. 

The maximum number of files that can be 
merged is 8. 

SORT INPUT DD STATEMENTS 



The input data set is 
ddname that appears as t 
of the system-name in an 
the COBOL source program 
option is specified, the 
generate an input proced 
the data set, read the r 
records and close the da 



associated with a 
he ddname portion 

ASSIGN clause in 
. When the USING 

compiler will 
ure that will open 
ecords, release the 
ta set. 



SORT OUTPUT DD STATEMENTS 



The output data set is associated with a 
ddname that appears as the ddname portion 



SORT HORK DD STATEMENTS 



The sort program requires at least three 
work data sets. The ddname for each DD 
statement is in the form SORTWKnn, where nn 
is a decimal number. The ddnames for the 
required data sets must be SORTSfKOI, 
SORTWK02, and SORTWK03. Additional work 
data sets may be defined, but their ddnames 
must be consecutively numbered, beginning 
with 04. 



SQSTWR nn Data Set Considerations 



Intermediate data sets (i.e., SORTWKnn 
data sets) for a sort/merge may be assigned 
to either magnetic tape or mass storage 
devices. All of the intermediate storage 
for one sort/merge must be assigned to the 
same device type. These may not be on both 
7-track and 9-track tape units in the same 
sort. Any one of the following devices may 
be used for intermediate storage: 

IBM 2400-series Magnetic Tape Unit (7- 

or 9-track) 
IBM 3400-series Magnetic Tape Unit 

(9-track) 
IBM 2314/2319 Direct Access Storage 

Facility 
IBM 3330 Direct Access Storage 

Facility 
IBM 3340 Direct Access Storage 

Facility 
IBM 3350 Direct Access Storage 

Facility 

The So rt/flerge Programmer ' s Gui de contains 
detailed information about these devices. 

Since spanned records can be input to 
and output from the sorting operation, it 
is the user's responsibility to assign the 
sort work files to mass storage devices 
whose track sizes are larger than the 
logical record size of the records being 
sorted. An S-mode file whose logical 
record length is greater than its track 
size may be sorted by assigning the work 
files to a magnetic tape unit. 
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If data sets not invo 
or merging operation are 
units, these tape units 
work files by using the 
For example, if PAYROLL 
ddname of the ASSIGN cla 
statement* the tape unit 
PAYROLL could be used as 
by using the following D 



lved in the sorting 
assigned to tape 
nay be used as sort 
UNIT=AFF parameter, 
is specified as the 
use in a SELECT 
assigned to 
a sort work file 
D statement: 



//PAYROLL DD UNIT=2 400, . . . 
//SORTWK02 DD CJNIT=AFF=PAYROLL. . . 



SORTWKnn DD St atements 



SORTWKnn data sets may be contained on 
tape or mass storage volumes. When mass 
storage space is assigned, only the primary 
allocation is used by the sort, and it must 
be contiguous. 



Note that the SORTWKnn data sets: 



1. May not be spread over more than one 
device type. 



Input D P Statement 



The input data set must reside on a 
physical device, a magnetic tape unit, a 
mass storage device, or in the system input 
stream. The following example shows DD 
statement parameters that could be used to 
define a cataloged input data set. 

//INSOBT DD DSNAME=INPT, X 

// DISP= (OLD, DELETE) 



2. May not be on 7-track tape when the 
input data set is on 9-track tape. 

3. May be on 7-track tape when the 
output data set is on 9-track tape. 

4. Cannot use the data conversion feature 
if they are on 7-track tape. The 
TRTCH subparameter must reflect this, 

5. May be on 9-track tape when the input 
data set is on 7-track tape. 



These parameters cause the system to search 
the catalog for a data set named INPT 
(DSNAME parameter) . When found, the data 
set is associated with the ddname IN SORT 
and used by the sort program. The control 
program obtains the unit assignment and 
volume serial number from the catalog, and 
displays a mounting message to the 
operator. The DISP parameter indicates 
that the data set has already been created 
(OLD). It also indicates that the data set 
should be deleted (DELETE) after the 
current job step. 



Out put DP St atment 



SORTWKnn Example A: The following DD 
statement parameters could be used to 
define a tape intermediate storage data 
set: 



//SQRTWK01 DD 
// 



UNIT=2400,LABEL=(,NL) , 
VOLUME=SEE=DOMMY 



These parameters s 
set on a 2 400-seri 
DSNAME parameter i 
assigns a unique n 
omission of the DI 
system to assume t 
and that it should 
the current job st 
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pecify an unlabeled data 
es tape unit. Since the 
s omitted, the system 
ame to the data set. The 
SP parameter causes the 
hat the data set is new 

be deleted at the end of 
ep. The 2400-series tape 
ly of the 9-track format. 



The output DD statement must define all 
of the characteristics of the output data 
set. The following example shows DD 
statement parameters that could be used to 
characterize an output data set: 



//OUTSORT DD 
// 



DSNAME=QUTPT,UNIT=2400, 
DISP=(NEW,CATLG) 



X 



The DISP parameter indicates that the data 
set is unknown to the operating system 
(NEW) and that it should be cataloged 
(CATLG) under the name OOTPT (DSNAME 
parameter) . The UNIT parameter specifies 
that the data set is on a 2400-series tape 
unit. 



SORTWKnn Example B: The following DD 
statement parameters could be used to 
define a mass storage interiediate storage 
data set: 



//SORTWK01 DD 
// 



UNIT=2314, X 

SPACE=(TRK, (200) ,,C0NTIG) 



These parameters specify a mass storage 
data set with a standard label (LftBEL 
parameter default value). The SPACE 
parameter specifies that the data set is to 
be allocated 200 contiguous tracks. The 
system assigns a unique naae to the data 
set and deletes it at the end of the job 
step. 
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ADDITIONAL DD STATEMENTS 



The sort/merge program requires two 
additional DD statements: 

//SYSOUT DD SYSOUT=A 

which defines the system output data set. 

//SORTLIB DD DSNAME=S YS1 . SORTLIB, X 
// DISP=SHR 

which defines the library containing the 
SORT/MERGE modules. 

Note: At OS/VS sort/Merge installation 
time, the programmer can designate that 
Sort/Merge diagnostic messages be printed 
on a specified data set. The FLAG option 
determines whether the messages directed to 
this data set are either 
uncorrectable-error messages or both 
informational and uncorrectablele-error 
Sort/Merge messages. In either case, 
uncorrectable-error messages are displayed 
on the console. SYSOOT is the default data 
set that is modified by the FLAG option. 
If there are DISPLAY or EXHIBIT statements 
in the COBOL program, the Sort/Merge 
messages cannot be routed to the same data 
set designated for the output of the 
DISPLAY and/or EXHIBIT statements. 
Therefore, one of the following courses of 
action should be considered: 

• The Sort/Merge default data set should 
be changed at installation time by 
specifying the PHINT=parameter and 
selecting a DD name other than SYSOOT. 
At execution time, the selected DD name 
must be specified on a DD statement. 

• In the COBOL source program, a DD name 
other than SYSOOT should be placed in 

the SORT-MESSAGE special register prior 
to the SORT statement. At execution 
time, the selected DD name must be 
specified in a DD statement. 

• At compile time, the SYSOOx option can 
be used to designate a file for COBOL 
DISPLAY output other than SYSOUT. 
Therefore, Sort/Merge messages can go 
to the SYSOOT file. 



SHARING DEVICES BETWEEN TAPE DATA SETS 



A single tape unit may be assigned to 
tso sort data sets when the data sets are 
one of the following pairs: 

• The input data set and the first 
intermediate storage data set 
(SORTWK0 1). 



• The input data set and the output data 
set. 

The AFF subparameter of the UNIT 
parameter can be used to associate the 
input data set with either the SORTWK01 
data set or the output data set. The 
subparameter can appear in the DD statement 
for SORTWK01 or output. 



USING HOSE THAN ONE SORT/MERGE , STATEMENT IN 
A JOB 



More than one SORT/MERGE statement may 
be used in a single program or in two or 
more programs that are combined into a 
single load module. 



SORT PROGRAM E XAMPLE 



The control cards in Figure 151 could be 
used with the sample program that 
illustrates the Sort feature. A 
description of the Sort Feature can be 
found in the publication IBM VS COBOL for 
OS/VS. 



NY838670165, 
•J. SMITH* , 
MSGLEVEL=1 
COBOCLG 

* 



I//SORTEST JOB 

I// 

I// 

I//S0RTJS3 EXEC 

J//COB.SYSIN DD 

i 

i 



(COBOL source program] 



I 
i 

I//GO. SORTWK01 DD 

I// 
I// 
I//GO. SORTHK02 DD 

I// 
I// 

I//GO.SORTWK03 DD 

1// 
I// 

I//GO. 00TSORT DD 

I// 
J// 

J //GO. SYSOOT DD 
J//GO. SORTLIB DD 

J// 

I//GO.INFILE DD 

I// 
1// 



UNIT=2314, 

SPACE= (TRK, (2 00) , 

,CONTIG) 

0NIT=2314, 

SPACE=(THK, (200) , 

,CONTIG) 

UNIT=2314, 

SPACE=<THK, (200) , 

,C0NTIG) 

0NIT=183, 

LABEL= (,NL) , 

VOL0ME=SER=NONE 

SYSO0T=A 

DSNAME=SYS1.S0RTLI 

DISP=SHR 

UNIT=182, 

LABEL=(,NL) , 

VOL0ME=SES=D0MHY 



1 

XI 
XI 

t 
1 
I 
I 
I 
I 
I 
I 
I 
I 
I 

X| 
X| 

I 

X| 

XI 

I 

X| 
X| 

I 

X| 
X| 

1 
I 

B,X| 

I 

X| 

XI 

I 

J 



Figure 151. Sort Feature Control Cards 
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The minimum number of SORTWKnn data sets 
are used; the sort operation can be 
optimized by using additional work data 
sets (see the appropriate Sort/flerge 
Programmer's Guide ) • 



— Successful completion of 
Sort/Merge 
16 — Unsuccessful completion of 
Sort/Merge 



CATALOGING SORT/MERGE DP STATEMENTS 



Since repeated use of the Sort/Merge 
feature often involves the same execution 
time DD statements, the user may wish to 
catalog them (see "using the Cataloged 
Procedures") . 



LINKAGE RITH THE SORT/MERGE PROGRAM 



Communication between the Sort/Merge 
program and the COBOL program is maintained 
by the COBOL library subroutine ILBOSMGO. 
This routine links to the sort/Merge 
program using the load module name SORT. 
It is the user's responsibility to set up 
his LINKLIB/STEPLIB in such a way that an 
alias or load module name of SORT/MERGE 
points to the first module of the 
Sort/Merge program he wishes to use. The 
programmer must also designate via the 
appropriate SORTLIB DD statement the 
library of the Sort/Merge program he wishes 
to use. 

If the INPOT PROCEDURE option of the 
SORT/MERGE statement is specified, exit E15 
of the Sort/Herge program is used. The 
return code indicating "insert records" is 
issued when a RELEASE statement is 
encountered, and the return code indicating 
"do not return" is issued when the end of 
the procedure is encountered. 

If the OUTPUT PROCEDURE option is 
specified, exit E35 of the Sort/Merge 
program is used. The return code 
indicating "delete records" is issued when 
a RETURN statement is encountered, and the 
return code indicating "do not return" is 
issued when the end of the procedure is 
encountered. (For additional information, 
about the Sort/Merge program, see the 
appropriate Sort/Herge Programmer's Guid e.) 



Com pletio n Codes 



The Sort/Herge program returns a 
completion code upon termination. This 
code may be interrogated by the COBOL 
program. The codes are: 



SUCCESSFUL COMPLETION: When a Sort/Merge 
application has been successfully executed, 
a completion code of zero is returned and 
the sort terminates. 



UNS UCCESSF UL COMPLETION: If the 
sort/merge, during execution, encounters an 
error that will not allow it to complete 
successfully, it returns a completion code 
of 16 and terminates. (Possible errors 
include an out-of-sequence condition or an 
input/output error that cannot be 
corrected.) The Sort/Merge programmer's 
Guide contains a detailed description of 
the conditions under which this termination 
will occur. 

The returned completion code is stored 
in a special register called SORT-RETURN by 
the COBOL library subroutine; an 
unsuccessful termination of the sort may 
then be tested for and appropriate action 
specified. Note that the contents of 
SORT-RETURN will change with the execution 
of a SORT statement. The following is an 
example of the use of SORT-RETURN with the 
sort feature: 

SORT SALES-RECORDS ON ASCENDING KEY 
CUSTOMER-NUMBER, DESCENDING KEY DAYTE, 
USING FN-1, GIVING FN-2. 

IF SORT-RETURN NOT EQU ftL TO ZERO, 
DISPLAY 'SORT UNSUCCESSFUL' UPON 
CONSOLE, STOP RUN. 

If no references to SORT-RETURN are made in 
a program, an unsuccessful sort will 
generate the following message: 

IKF888I- UNSUCCESSFUL SORT FOR SD 
SORT-FILE DDNAME 



See "Appendix K: Diagnostic Messages" for 
a description of action to be taken. 

A normal Sort/Merge operation will 
produce the following messages from the 
OS/VS Sort/Merge program: ICE036I, 
ICE037I, ICE038I, ICE045I, ICE049I, 
ICE052I, ICE054I, and ICE055I. Other 
messages may appear depending on the COBOL 
options specified. 

If the OS Sort/Merge program product is 
used, the same messages will appear with 
the same numbers, but the three-character 
prefix will be different. 



Using the Sort/Merge Feature 371 



TERMINATING THE SORT PROGRAM FROM THE COBOL 
PROGRAM 



LOCATING L AST RECORD, RELEASED TO SQRT/MgRGE 
BY AN INPUT PROCEDURE 
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LOCATING SORT/MERGE RECORD FIELDS 



Records defined under a COBOL SD are 
assigned a BLL {Base Locator for Linkage 
Section) , or a BL (Base locator) if SAME 
RECORD AREA is specified. Location of a 
given data item in an object-time dump when 
the record in which it is contained 
references a BLL can be determined as 
follows: 



For debugging purposes, it is sometimes 
useful to determine the last input record 
released to the Sort/Merge program. The 
following procedure should be used: 

1. From the Data Division map, determine 
the BLL number of the SORT/MERGE file 
being processed at the time of program 
termination. Assume it is BLLn. 

2. From the Task Global Table map, 
determine the location of the BLL 
cells in the COBOL object program. 

3. The nth BLL in the main storage dump 
will point to the last record released 

to SORT/MERGE. 

Note: This BLL is initialized when control 
is first transferred to the input 
procedure. Thus, if the program terminates 
before control ever goes to the input 
procedure, the BLL will not be initialized. 
Also, with a USING clause in a SORT 
statement, the BLL will not be initialized. 



1. From the compilation listing, 
determine: 

a. The displacement of the item (see 
Data Division Map) . 

b. The relative address of the BLL 
CELLS (see the Memory Map Table) . 

c. The BLL number. 



From the dump, determine the 
relocation factor (USE/EP) . 



Add the relative address of the BLL 
CELLS to the relocation factor to 
obtain the absolute BLL CELLS address 
in the dump. 



4. Each BLL is 4 bytes long; they are 
located in ascending sequence, 
beginning in the dump at the address 
computed in Step 3 BLL=1 is the first 
4 bytes, BLL=2 is the second 4 bytes, 
etc. Find the appropriate 4 bytes. 

5. The 4 bytes obtained in Step 4 contain 
the absolute base address of the 
desired record. Add the item's 
displacement to it to obtain the 
absolute address of the leftmost byte 
of the field in the dump. 



SORT/MERGE CHECKPOINT/RESTART 



The CHECKPOINT/RESTART feature is 
available to the programmer using the COBOL 
SORT/MERGE statement. In order to initiate 
a checkpoint, the programmer uses DD 
statements and the RERUN clause. The DD 
statement for use in taking a checkpoint is 
discussed in "Using the Checkpoint /Res tart 
Feature. * 

The RERUN clause is used to indicate 
that checkpoints are written, at logical 
intervals determined by the sort/merge 
program, during the execution of all 
SORT/MERGE statements in the program. This 
RERUN clause is fully described in the 
publication IBty OS Full Am erican National 
Standard COBOL. 



EFFICIENT PROGRAM USE 



The information you give the Sort/Merge 
program about the application it is to 
perform helps the sort and merge phases to 
produce a fast, efficient sort or merge. 
Hhen you do not supply information such as 
data set size and record format, the 
program must make assumptions, which, if 
incorrect, lead to ineffiency. 
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DATA SET SIZE 



The most important information one can 
give is an accurate data set size using the 
SORT-FILE-SIZE special register. If the 
exact number of records in the input data 
set is known, that number should be used as 
the value. If the exact number is not 
known, an estimate should be made. When 
the Sort/Merge program has accurate 
information about data set size, it can 
make the most efficient use of both main 
storage and intermediate storage. 



MAIN STORAGE REQUIREMENTS 



If the maximum amount of main storage to 
be used by the sort/Merge program was not 
specified at installation time, the program 
assumes a maximum of 15,50 bytes. The 
sort program reguests 12,000 bytes leaving 
3500 bytes for system functions. 
Performance usually improves as the program 
is given more main storage. A minimum of 
44K bytes of main storage is normally 
needed for efficient execution of the 
sort/merge program, and performance may 
increase as more main storage is made 
available. 



If the amount of main storage was 
specified at system generation time, it is 
the programmer* s responsibility to ensure 
that the Sort/Merge program has at least 
that much main storage available in 
addition to the space needed for Data 
Management and the COBOL program. If this 
amount of main storage is not available, 
the program will terminate abnormally. 

The programmer may alter, dynamically 
within the COBOL program, the main storage 
default values for the Sort/Merge program. 
The SORT-CORE-SIZE special register may be 
used to communicate, changes to the 
Sort/Merge program. In general, a positive 
value placed in SORT-CORE-SIZE denotes the 
amount of storage the programmer is 
allocating for use by the Sort/Merge 
program. For example, the statement "MOVE 
30000 TO SORT-CORE-SIZE" means that 30000 
bytes of storage are available to the 
Sort/Merge program. Accordingly, if 30000 
is moved to SORT-CORE-SIZE, COBOL 
communicates to Sort/Merge that 30000 bytes 
of storage are available to it. There are, 
in addition, two other uses for 
SORT-CORE-SIZE. 

Special considerations apply when a 
Sort/Merge program product is used. If the 
program product is installed with the 
SIZE=MAX option, the program allocates all 



remaining available main storage in a 
region for its own use. If an input 
procedure then attempts to open a file, an 
80A abnormal termination may result if 
buffers and necessary data management 
modules have not already been loaded, since 
no more space is available. 

If instead, a negative value is placed 
in the special register prior to execution 
of the sort, the program uses the default 
SIZE option specified at installation, but, 
if SIZE=MAX was specified, sets aside that 
absolute value before obtaining the 
remainder. Also, if ALL *9» (or +999999) 
is moved to SORT-CORE-SIZE prior to a sort 
operation, the program executes with the 
SIZE=MAX option, regardless of the 
installed value, while reserving 6K bytes 
of main storage for use by the data 
management routines and buffers. 

The sort/Merge program product may also 
be installed with a default reserved main 
storage parameter that will be used if no 
negative value is passed from COBOL. For 
additional information about these options 
see the appropriate Sor t/M erge Installation 
iL&£e re nc e_|fa nua 1 . 
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'HERGE DIAGNOSTIC MESSAGES 



The messages generated by the Sort/Merge 
programs Feature are listed in the 
appropriate Sort/Merge Installation 
Reference Manual and So rt/ Merge 
Programmer's Guide . 

When the Sort/Merge program is 
installed, the user can elect to have 
messages sent to the printer, in which case 
a DD card with a ddname of SYSOUT must be 
included in the job step. The programmer 
can dynamically alter the ddname of the 
file on which Sort/Merge is to write its 
messages. If Sort/Herge has been installed 
with provision for routing its messages to 
the printer, then the programmer can place 
in the SORT-MESSAGE special register the 
ddname that Sort/Merge is to substitute 
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forSYSOUT, for message routing. For 
example, when the statement MOVE "SORTDDNM" 
TO SORT-MESSAGE is executed before sort is 
initiated, then the sort writes its printer 
messages to the data set S08TDDNM rather 
than to SYSOUT- If SORT-MESSAGE is not 
refered to in the program, the ddname that 
was specified at Sort/Merge installation 
time is the default value. 

One technique for specifying the 
sort/merge print file ddname would be to 
include source language and job control 
language statements as follows: 

* Linkage Section 

01 SORT-PARAMETERS. 

05 PARAMETER-COUNT PIC 9(4) USAGE COMP. 

05 SORT-DDNAME PIC X{8). 

* Imme di ately , preceding the s ort 
operation 

IF PARAMETEB-COUNT IS NOT EQUAL TO 
MOVE SORT-DDNAME TO SORT-MESSAGE. 

* On the EXEC card 

//GOSTEP EXEC PGM= program-name, 
PARM=*SORTDDNM« 



Note: This technique of assigning a unique 
value to SORT-MESSAGE without modifying or 
recompiling the program can also be applied 
to the special registers S08T-CORE-SIZE, 
SORT-MODE-SIZE, and SORT-FILE-SIZE. 



SORTING VARIABLE-LENGTH RECORDS 



Figure 152 illustrates one way to sort 
variable-length records described by the 
OCCURS clause with the DEPENDING ON option. 
If the FD»s (file- name description) and the 
SD's (sort-file- name description) are 
defined as in this figure, where the record 
descriptions of the FD's and the SD 
correspond, possibilities for error arise. 
It is suggested, therefore, that the user 
consider the following: 



1. Specification of the statement 



SORT SORT-FILE USING INPUT-FILE.. 



would probably lead to incorrect 
results. This statement implies a 
READ ... INTO ... statement; that 
is, after INPUT-FILE has been read, 
the record is moved to AAA. However, 
because the user must set the length 
of this receiving field prior to 
moving A to AAA but cannot do so, the 
compiler may use an incorrect length 
that results in abnormal termination. 
Instead, the user should substitute an 
input procedure for the USING option, 
as in the section of code labeled 
PARA2B in the example. 



2. similarly, the statement 



SORT SORT-FILE... GIVING OUTPUT- FILE 



DEFINING VARIABLE-LENGTH RECORDS 



If the input records used are of 
variable length, the record length that 
occurs most frequently in the input data 
set (modal length) should be put into the 
special register SORT-MODE-SIZE. This 
value is used to help define a data set 
based on a particular length. If a value 
is not specified, the SORT/HERGE program 
assumes it is equal to the average of the 
maximum and minimum record lengths in the 
input data set. If, for example, the data 
set contains mostly small records and just 
a few long records, the SORT/MEBGE program 
would assume a high modal length and would 
allocate a larger record storage area than 
necessary. Conversely, if the data set 
contains just a few short records and many 
long records, the SORT/MERGE program would 
assume a low modal length and might not 
allocate a large enough record storage area 
to sort data. For a complete discussion, 
see the appropriate Sort /Mer ge Programmer' s 
Guide. 
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3. If a SORT record contains an item with 
an OCCURS DEPENDING ON clause and the 
size of the SOBT record description 
with the minimum number of occurences 
of the item represent the smallest 
SORT record, the minimum SORT record 
length is not reflected in the minimum 
record length parameter passed to 
SORT. This may result in inefficient 
SORT performance. The problem can be 
avoided by specifying a dummy SORT 
record of a fixed length (no OCCURS 
DEPENDING ON) with the size of the 
smallest SORT record described with 
OCCURS DEPENDING ON clauses. 
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SOBT/HERGE FOR ASCII FILES 



For sorting ASCII files, the normal 
EBCDIC collating sequence is provided 
unless the user specifies otherwise. 

To specify a sort/merge using the ASCII 
collating sequence, the programmer may 
include and identify a program collating 
sequence of STANDARD-1 (equivalent to 
ASCII). If LANGLVL(1) is specified, the 
programmer may alternatively include the 
"C" organization entry in the ASSIGN clause 
for the file-name associated with the file 



to be sorted or merged. No buffer offset 
may be given with the sort/serge feature. 



OTHER, COLLATING SEQUENCES^ 

Through use of the COLLATING SEQUENCE 
clause of the sort/merge feature, the 
programmer can identify other (non-EBCDIC 
and non-ASCII) collating sequences to be 
used. See "Collating Sequences" in the 
section "Programming Techniques." 
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r 



01 



Part 1 

IDENTIFICATION DIVISION. 
PROGS AM-ID. VLSOBT. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT .... 

SELECT 

SELECT .... 
DATA DIVISION. 
FILE SECTION. 
FD INPUT-FILE. 

LABEL RECORDS ARE OMITTED 

DATA HE CORD IS A. 

A. 

B PIC 99. 

C OCCURS 1 TO 10 TIMES 
DEPENDING ON B. 
3 D PIC 9 9. 
3 E PIC XX. 
OUTPUT- FILE 

LABEL RECORDS ARE OMITTED 
DATA RECORD IS AA. 
A A. 

BB PIC 99. 

CC OCCURS 1 TO 10 TIMES 
DEPENDING ON BB. 
03 DD PIC 99. 
03 EE PIC XX. 
SORT-FILE 

DATA RECORD IS AAA. 
AAA. 



02 
02 



FD 



01 



02 
02 



SD 



01 



02 BBB PIC 99. 

2 CCC OCCURS 1 TO 10 TIMES 

DEPENDING ON BBB. 

03 DDD PIC 99. 

03 EEE PIC XX. 



Part 2 

PROCEDURE DIVISION. 
PARI SECTION. 

SORT SORT-FILE ASCENDING KEY BBB 

INPUT PROCEDURE PAR2 

OUTPUT PROCEDURE PAR3. 
STOP RUN. 
PAR2 SECTION. 
PAR2A. 

OPEN INPUT INPUT-FILE. 
PAR2B. 

READ INPUT-FILE AT END GO TO PAR2C. 

MOVE B TO BBB. 

RELEASE AAA FROM A.» 

GO TO PAR2B. 
PAR2C. 

CLOSE INPUT-FILE. 
PAR2-EXIT. 

EXIT. 
PAR3 SECTION. 
PAR3A. 

OPEN OUTPUT OUTPUT-FILE. 
PAR3B. 

RETURN SORT-FILE AT END GO TO PAR3C.2 

MOVE BBB TO BB. 

WRITE AA FROM AAA. 

GO TO PAR3B. 
PAR3C. 

CLOSE OUTPUT-FILE. 
PAR3-EXIT. 

EXIT. 



FROM clause, which implies a MOVE 



*When using a sort input procedure, the RELEASE . 

and then a RELEASE, should always be preceded by a MOVE that sets the length of the 

receiving field (AAA, in this example) . 
* When using a sort output procedure, the RETURN -. 

the RETURN and then a MOVE, should never be used. 

the correct length of the receiving field. 



INTO ... clause, which implies 
There is no way for the user to set 



Figure 152. Sorting Variable- Length Records Whose File-name Description and 
Sort- File-name Description Correspond 
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OS/YS SORT/MERGE DEBUG FEATURE 



& DEBUG control statement may be included at execution time to assist in debugging 
Sort/Herge problems. The ABEHD operand of the DEBUG statement can be used to override 
the NOABEND default of the installation keyword ERRET. The format of the COBOL 
SORT-DEBUG statement is: 

bDEBUGb operands 

The operands and their meanings are as follows: 

(ABEND ) Overrides the generated default for action to be taken when the 

(NOABENDj program encounters an uncorrectable error. 

CLOCK Instructs the program to measure elapsed and CPU times for the 

different PEER phases. 

FLAG (x + [ ,x<... ,x° ]) Instructs the program to print PEER information messages 

(ICE120-124) . The values which may be given to x are as 
follows: 

a Messages from all phases (ICE120-124) 

Phase messages ICE120) 

C Phase 1 messages (ICE 121) 

P Phase 2 (partition) messages (ICE124) 

R Phase 2 (reduction) messages (ICE122) 

E Phase 3 messages (ICE12 3) 

CTRO=value The program should keep a count of work I/O operations; when 

the count reaches "value", it should ABEND. 

EM=value "Value" should be used as the maximum number of strings to be 

merged in the final merge pass. 

RM=value "Value" should be used as the maximum number of strings to be 

merged in intermediate merge passes. 

CB=value "Value" is the number of Phase 1 work buffers. 

RB=value "Value" is the number of Phase 2 work buffers. 

EB=value "Value" is the number of Phase 3 work buffers. 

BT=value Instructs the program to calculate the blocking factor for 

intermediate storage in such a way that "value"is the number of 
buffers per track. 

For more detailed information on the continuing in column 16 of card 2. 

DEBUG feature and the messages generated by Comments may be continued on a second card 

the use of the above operands, see the by having a nonblank character in colunn 72 

publication OS/VS Sort/Herge Programmer' s of card 1 and continuing in column 16 of 

Guide. card 2. 

Operands must be separated by commas. 
Operands may be continued on a second card Use of the COBOL SORT-DEBUG statement 

either by following the last operand on reguires the following DD statement: 
card 1 by a comma and continuing on card 2 

in columns 2-16, or by having a nonblank //SRTCDS DD * 
character in column 72 of card 1 and DEBUG Statement 
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USING THE SE GMENTA TION FEATORE 



Although Release 2 of the OS/VS COBOL 
compiler will accept a source program 
containing segmentation specifications, it 
will not produce an actual overlay 
structure. Instead, it combines all 
segments into one single object program in 
segment order, and allows the paging of the 
VS operating system to perform any overlay. 
The absence of actual COBOL-performed 
overlay is usually not a problem in the 
OS/VS environment, since adequate main 
storage is available for even the largest 
programs . 

The following discussion is provided 
only for those users who — while recognizing 
that this compiler will not provide 
overlay — nevertheless wish to write or 
maintain programs that include segmentation 
statements. 

Segmentation provides a means of 
dividing the Procedure Division of a source 
program into sections. Through the use of 
a system of priority numbers, certain 
sections are designated as fixed segments 
(either fixed permanent or fixed 
overlayable) and others as independent 
segments. 



Suppose that the program 
segmented as shown in Figure 
those segments having priori 
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Fixed overlayable segments are sections 
that are less frequently used. These 
sections are sometimes made available in 
the state in which they were last used {see 
ISil_VS_COBOL_for_OS/VS) . They are 
distinguishable here by the fact that they 
have been assigned priority numbers greater 
than the segment limit, but less than 50. 

Independent segments are those assigned 
priority numbers greater than ^9 and less 
than 100 (section-5 and section-7 in this 
example) . 



IDENTIFICATION DIVISION. 
PROGRAM-ID. SAVECORE. 

ENVIRONMENT DIVISION. 

OBJECT-COMPUTER. IBM-370 
SEGMENT-LIMIT IS 15. 

DATA DIVISION. 



PROCEDURE DIVISION. 
SECTION-1 SECTION 8. 



SECTION-2 SECTION 8. 



SECTION-3 SECTION 16. 



SECTION-4 SECTION 8. 



SECTION-5 SECTION 50. 



SECTION-6 SECTION 16. 



SECTION-7 SECTION 50. 



Figure 153. Segmentation of Program 
SAVECOSE 

OSING THE PERFORM STATEMENT IN A SEGMENTED 
PROGRAM 



When the PERFORM statement is used in a 
segmented program, the programmer should be 
aware of the following: 
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A PERFORM statement that appears in a Mte: As an extension to American 
section whose priority-number is less National Standard COBOL, the OS/VS 
than the segment limit can have within COBOL Compiler allows sections with any 
its range only (a) sections with priority-number to fall within the 

priority-numbers less than 50, and (b) ran <? e of a PERFORM statement. 
sections wholly contained in a single 

segment whose priority-number is * A PERFORM statement that appears in a 

greater than 49. section whose priority-number is equal 

to or greater than the segment limit 
can have within its range only (a) 
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sections with the same priority-number 
as the section containing the PERFORM 
statement, and {b) sections with 
priority-numbers that are less than the 
segment limit. 

Note : As an extension to American 
National Standard COBOL, the OS/VS 
COBOL Compiler allows sections with any 
priority-number to fall within the 
range of a PERFORM statement. 

When a procedure-name in a segment with 
a priority-number less than the segment 
limit referred to by a PES FORM 
statement in a segment with a 
priority-number greater than the 
segment limit, the independent segment 
will be reinitialized upon exit from 
the PERFORM. 



segment. Called subprograms are loaded 
with the fixed portion of the main program 
and assigned a priority of zero. 
Otherwise, the program executes just as if 
it were not segmented. 



LANGLVL OPTION AND RE-INITIALIZATION 



The LANGLVL compile option chosen by the 
user affects the degree and manner of 
re-initialization COBOL will perform on 
independent segments, since there is a 
difference between the 1968 and 1974 ANS 
definitions. For further details, consult 
the language manual IBM VS COBOL f or OS/VS. 



OPERATION 



COMPILER OUTPUT 



Execution of the object program begins 
in the root segment; i.e., the first 
segment in the permanent segment. If the 
program contains no permanent segments, or 
if the first section to be executed in the 
program is not part of the root segment, 
the compiler generates a dummy segment 
thatwill initiate the execution of the 
first independent segment. All global 
tables, literals, and data areas are part 
of the root segment. Called object-time 
subroutines are also part of the root 



The output produced by 
group of segments organize 
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Figure 154 shows the output of a sample 
segmentation program. 
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IDENTIFICATION oIVlSION. 
PROGRAM-ID. SEu-S AMPLE. 
AUTHOR. PROGRArtMER-NAME. 
REMARKS. 

SPECIAL OPERATOR INSTRUCTIONS - NONE. 

INPUT REQUIRED - NONE. 

PURPOSE 

TO CREATE A SINGLE FILE ON DISK USING 
QSAM/DTFSD, AND READ IT BACK. 
PROGRAM USES SEGMENTATION 
WITH FIi_E PROCESSING SPREAD OVER 
THE PERrtANENT, OVERLAYABLE FIXEDt 
AND INOcPENDENT SEGMENTS. 
EXPECTED RESULTS 

START TcST SEG-SAMPLE 

(EACH ScGMENT DISPLAYS ITS SEGMENT NUMBER 
AND FUNuTIUNl 

END TEST SfcG-SAMPLE SUCCESSFUL RUN 
SECTION* WHILE WRITING APPEAR 
IN ORDtK 80t 20t 30 t 60, 40. 
SECTION* WHILE READING APPEAR 
IN ORDtK 80. 60, 30, 40, 20. 
ERROR INDICATIONS 

**ERROR DISK SEQ I/O** 

**ERROR END OF EXTENT WRITING AFTER (RECORD)** 

**ERROR UNEXPECTED EOF READING AFTER 

RECuRO (RECNO)** 
**ERROR EOF NOT FOUND** 
**RECORo IS (RECNO) 

SHOULo BE (RECNO)** 
PROGRAM CONTAINS PERFORMS FROM BASE SECTION 
TO PERMANENT, OVERLAYABLE FIXED, AND INDEPENDENT 
SEGMENT*. 

ALSO CONTAINS PERFORMS FROM INDEPENDENT TO PERMANENT 
AND FROil OVERLAYABLE FIXED TO PERMANENT SEGMENTS. 
ALSO CONTAINS PERFORMS ENTIRELY WITHIN A SEGMENT IN 
IN EACH CATEGORY. 
ENVIRONMENT DIViSION. 
CONFIGURATION ScCTION. 
SOURCE-COMPUTER. IBM-370. 
OBJECT-COMPUTER. IBM-370 

MEMORY SIZE 6<»000 CHARACTERS 
SEGMENT-LIMiT IS 25. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-1 ASSIGN TO DA-2314-S-DKSQ01A. 

DATA DIVISION. 
FILE SECTION. 
FD FILE-1 

RECORDING MODE IS F 
LABEL RECORoS OMITTED 
DATA RECORD IS RECFD1. 
01 RECFD1 PICTURE X(83). 
WORKING-STORAGE SECTION. 
77 ERRORSW PIC A VALUE SPACE. 
77 ERCTFL PIC S99 VALUE ZERO. 
77 MSGHDR PIC X( 22) VALUE '**ERROR DISK SEQ I/O**'. 



00154790 



00154820 
00154830 
00154840 
00154850 
00154860 
00154870 
00154880 
00154890 
00154900 
00154910 
00154920 

00154940 
00154950 

00154970 
00154980 
00154990 
00155030 
00155010 
00155020 
00155030 
00155040 
00155050 
00155060 
00155070 
00155080 
00155110 
00155120 
00155130 
00155140 
00155150 
00155160 
00155170 
00155180 
00155190 
00155200 
00155210 
00155220 
00155230 
00155240 
00155250 
00155260 
00155270 
00155280 
00155290 
00155300 

00155310 
00155320 
00155330 
00155340 
00155350 
00155360 
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0OC58 
OCC59 
00060 
G0C61 
00042 
00C63 
CCC64 
00C65 
0CC66 
00C67 
00C68 
CCC69 
C0C7O 
00071 
00C12 
O0C73 
CCC14 
0CC75 
00076 
0CC77 
00C78 
CQC79 

cccec 

00C81 
O0C£2 
00C83 
00C84 
OOC85 
00086 
00C87 
00088 
C0C89 
CCC9C 
OCCSi 
0CC52 
00093 
00094 
0CC95 
000S6 
0CCS7 
OC098 
00C99 
001C0 
00101 
00102 
001C3 
00104 
C01C5 
001C6 
00107 
001C8 
001C9 
00110 
00111 
00112 
00113 
00114 



00065 O 
00066J 
00067U 
000680 
000690 
O0070O 
00C71O 
000720 
00073o 
000740 
00075o 
00076o 
000770 
00078c) 
OC079u 
000800 
000810 
000820 
000830 
00084J 
00085J 
00086o 
00087o 
000880 
0C0890 
000900 
000910 
00092o 
000930 
000940 
000950 
000960 
000970 
000980 
OC0990 
OOlOOo 
OOlOlo 
001020 
001030 
001040 
001050 
001060 
00107o 
00108o 
001090 
OOllOo 
001110 
001120 
001130 
00114o 
001150 
001160 
001170 
0C118O 
001190 
001200 
001210 



77 MSGEOX PIC A<36) 

VALUE '**ERkOR END OF EXTENT WRITING AFTER •. 
77 MSGEOF PIC X<37) 

VALUE '**ERKOR UNEXPECTED EOF READING AFTER '. 
77 MSGNEF PIC X( 23) VALUE « **ERROR EOF NOT FOUND**' 
01 REC1. 



02 
03 
03 
02 
66 



REC-ID. 
REC-HD 
REC-NO 
FILLER 



PIC X(4) VALUE 'RECD'. 
PIC S9(4J VALUE ZERO. 
PIC A(75) VALUE SPACES. 
RECIO RcNAMES REC-ID. 
01 VER-REC. 

02 VER-ID. 

03 VER-HD PIC X(4) VALUE 'RECD'. 
03 VER-NO PIC S9(4J VALUE ZERO. 

PROCEDURE DIVISION. 
BASE-SECTION SECTION 0. 

DISPLAY 'START TEST SEG-SAMPLE* . 

OPEN OUTPUT FILE-1. 

PERFORM W-80-O THRU W-80-9. 

PERFORM W-30-0 THRU W-30-9. 

PERFORM W-6O-0 THRU W-60-9. 

PERFORM W-40-0 THRU W-40-9. 
BASE-50. 

CLOSE FILE-i.. 

OPEN INPUT MLfc-1. 

PERFORM R-8O-0 THRU R-80-9. 

GO TO R-60-0. 
BASE-60. 

PERFORM R-40-0 THRU R-40-9. 

READ FILE-1 INTO REC1 AT END GO TO BASE-70. 

DISPLAY MSGriDR DISPLAY MSGNEF 

MOVE 'E' TO ERRORSW. 
BASE-70. 

CLOSE FILE-i. 
BASE-90. 

IF ERRORSW iS tQUAL TO 'E' 

DISPLAY 'ENO TEST SEG-SAMPLE UNSUCCESSFUL RUN" ELSE 

DISPLAY «ENU TEST SEG-SAMPLE SUCCESSFUL RUN'. 

STOP RUN. 
SECTION-20 SECTION 20. 
W-20-0. 

DISPLAY 'SECTION 20 WRITE'. 

NOTE ENTEREo BY PERFORM FROM W-80-0. 

PERFORM W-2i-0 THRU W-21-9 5 TIMES. 
W-20-9. 

EXIT. 
W-21-0. 

WRITE RECFDi. FROM REC1 INVALID KEY 

DISPLAY MSGHDR 

DISPLAY MSGcOX RECID 

MOVE 'E' TO ERRORSW 

GO TO BASE-aO. 

ADO 0001 TO REC-NO. 
W-21-9. 

EXIT. 
R-20-0. 



00155370 
00155380 
00155390 
00155400 
00155410 
00155420 
00155430 
00155440 
00155450 
00155460 
00155470 
00155480 
00155490 
00155500 
00155510 
00155520 
00155530 

00155550 
00155560 
00155570 
00155580 
00155590 
00155600 
00155610 
00155620 
00155630 
00155640 
00155650 
00155660 
00155670 
00155680 
00155690 
00155700 
00155710 
00155720 
00155730 



00155760 
00155770 
00155780 
00155790 
00155800 
00155810 
00155820 
00155830 
00155840 
00155850 
00155860 
00155870 
00155880 
00155890 
00155900 
00155910 
00155920 
00155930 



Figure 154. Sample Segmentation Program (Part 2 of 14) 
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CC115 


001220 


CQU6 


00123J 


CC117 


00124O 


001X8 


0012.5U 


00119 


001260 


C012C 


00127J 


00121 


001280 


0C122 


00129O 


0C123 


00130J 


00124 


00131o 


00125 


001320 


00126 


00133J 


00127 


O0134O 


0C128 


00135»> 


00129 


001360 


C012C 


00137o 


G0131 


00138^ 


00132 


00139J 


00123 


00140J 


00134 


001410 


C0135 


0C142U 


0136 


00143* 


CC137 


00 1440 


CC138 


00145J 


00139 


00146J 


C0140 


001470 


C0141 


00148o 


C0142 


00149o 


00143 


00150u 


00144 


001510 


0143 


001520 


CCI46 


001530 


00147 


001540 


C0148 


0C155O 


00149 


001560 


C01S0 


00157o 


CC151 


00158o 


00152 


001590 


C0153 


00160O 


C01S4 


00161O 


0C1S5 


001620 


00156 


00163o 


00157 


0C164o 


00158 


001650 


CC15S 


001660 


30160 


00167o 


00161 


0G168o 


CC162 


00169o 


00163 


001700 


CC164 


O0171O 


00165 


001720 


CG166 


OC173o 


00167 


001740 


C0168 


001750 


00169 


001760 


CC17C 


001770 


00171 


001780 



DISPLAY 'SEcTION 20 READ'. 00155940 

MOTE ENTEREO BY PERFORM FROM BASE-40. 00155950 

PERFORM R-2*-0 THRU R-21-9 5 TIMES. 00155960 

R-20-9. 00155970 

EXIT. 00155980 

R-21-0. 00155990 

READ FILE-1 INTO REC1 AT END 00156000 

DISPLAY MSGriDR DISPLAY MSGEOF 00156010 

ADO 4 TO ERcTFL MOVE • E' TO ERRORSW 00156020 

GO TO R-21-*. 00156030 

IF REC-ID li NOT EQUAL TO VER-ID 00156040 
DISPLAY MSGHDR DISPLAY 'EXPECTED • VER-ID • FOUND • REC-ID 00156050 

ADD 1 TO ERcTFL MOVE • E' TO ERRORSW 00156060 

MOVE REC-ID TO VER-ID. 00156070 

ADD 1 TO VEii-Nb. 00156080 

R-21-9. 00156090 

IF ERCTFL !.» GREATER THAN 3 00156100 

GO TO BASE-70. 00156110 

SECTION-30 SECTION 30. 00156120 

W-30^0. 00156130 

DISPLAY 'SECTION 30 WRITE'. 00156140 

NOTE ENTEREJ BY PERFORM FROM BASE-SECTION. 00156150 

PERFORM W-31-0 THRU W-31-9 11 TIMES. 00156160 

W-30-9. 00156170 

EXIT. 00156180 

W-31-0. 00156190 

WRITE RECFDj. FROM REC1 INVALID KEY 00156200 

DISPLAY MSGriDR 00156210 

DISPLAY MSGcOX RECID 00156220 

MOVE 'E' TO ERRORSW 00156230 

GO TO BASE-aO. 00156240 

ADD 0001 TO RfcC-NO. 00156250 

W-31-9. 00156260 

EXIT. 00156270 

R-30-0. 00156280 

OISPLAY 'SEcTION 30 READ'. 00156290 

NOTE ENTEREu BY GO TO FROM R-60-0. 00156300 

PERFORM R-3i.-0 THRU R-31-9 11 TIMES. 00156310 

GO TO BASE-oO. 00156320 

R-31-0. 00156330 

READ FILE-1 INTO REC1 AT END 00156340 

DISPLAY MSGriDR DISPLAY MSGEOF 00156350 

ADD 4 TO ERuTFL MOVE 'E' TO ERRORSW 00156360 

GO TO R-31-*. 00156370 

IF REC-ID I.s NOT EQUAL TO VER-ID 00156380 
DISPLAY MSGriDR DISPLAY 'EXPECTED • VER-ID ' FOUND ' REC-ID 00156390 

ADD 1 TO ERcTFL MOVE 'E» TO ERRORSW 00156400 

MOVE REC-ID TO VER-ID. 00156410 

ADD 1 TO VEk-NU. 00156420 

R-31-9. 00156430 

IF ERCTFL Ii GREATER THAN 3 00156440 

GO TO BASE-70. 00156450 

SECTION-40 SECTiON 40. 00156460 

W-40-0. 00156470 

OISPLAY 'SEcTION 40 WRITE'. 00156480 

NOTE ENTEREO BY PERFORM FROM BASE-SECTION. 00156490 

PERFORM W-4j.-0 THRU W-41-9 17 TIMES. 00156500 
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382 



00172 


001790 


00173 


001800 


00174 


001810 


00175 


001820 


00176 


001830 


00177 


001840 


00178 


001850 


00179 


001860 


00180 


001870 


00181 


001880 


00182 


001890 


00183 


001900 


00184 


001910 


00185 


001920 


00186 


001930 


00187 


001940 


00188 


001950 


00189 


001960 


00190 


001970 


00191 


001980 


00192 


001990 


00193 


002000 


00194 


002010 


00195 


002020 


00196 


002030 


00197 


002040 


00198 


002050 


00199 


002060 


00200 


002070 


00201 


002080 


00202 


002090 


00203 


002100 


00204 


002110 


00205 


002120 


00206 


002130 


00207 


002140 


00208 


002150 


00209 


002160 


00210 


002170 


00211 


002180 


00212 


002190 


00213 


002200 


00214 


002210 


00215 


002220 


00216 


002230 


00217 


002240 


00218 


002250 


00219 


002260 


00220 


002270 


00221 


002280 


00222 


002290 


00223 


002300 


00224 


002310 


00225 


002320 


00226 


002330 


00227 


002340 


00228 


002350 



W-40-9. 

EXIT. 
W-41-0. 

WRITE RECFD1 FROM REC1 INVALID KEY 

DISPLAY MSGHDR 

DISPLAY MSGEOX RECID 

MOVE 'E' TO ERRORSW 

GO TO BASE- 50. 

ADD 0001 TO REC-NO. 
W-41-9. 

EXIT. 
R-40-0. 

DISPLAY 'SECTION 40 READ". 

NOTE ENTERED BY PERFORM FROM BASE- 60. 

PERFORM R-41-0 THRU R-41-0 7 TIMES. 

PERFORM R-20-0 THRU R-20-9. 
R-40-9. 

EXIT. 
R-41-0. 

READ FILE-1 INTO REC1 AT END 

DISPLAY MSGHDR DISPLAY MSGEOF 

ADD 4 TO ERCTFL MOVE ' E* TO ERRORSW 

GO TO R-41-9. 

IF REC-ID IS NOT EQUAL TO VER-ID 

DISPLAY MSGHDR DISPLAY •EXPECTED * VER-ID 

ADD 1 TO ERCTFL MOVE »E" TO ERRORSW 

MOVE REC-ID TO VER-ID. 

ADD 1 TO VER-NO. 
R-41-9. 

IF ERCTFL IS GREATER THAN 3 

GO TO BASE-70. 
SECTION-60 SECTION 60. 
W-60-0. 

DISPLAY 'SECTION 60 WRITE*. 

NOTE ENTERED BY PERFORM FROM BASE-SECTION. 

PERFORM W-61-0 THRU W-61-9 13 TIMES. 
W-60-9. 

EXIT. 
W-61-0. 

WRITE RECFD1 FROM REC1 INVALID KEY 

DISPLAY MSGHDR 

DISPLAY MSGEOX RECID 

MOVE '£• TO ERRORSW 

GO TO BASE- 50. 

ADD 0001 TO REC-NO. 
W-61-9. 

EXIT. 
R-60-0. 

DISPLAY 'SECTION 60 READ'. 

NOTE ENTERED BY GO TO FROM BASE- 50. 

PERFORM R-61-0 THRU R-61-9 13 TIMES. 

GO TO R-30-0. 
R-61-0. 

READ FILE-1 INTO REC1 AT END 

DISPLAY MSGHDR DISPLAY MSGEOF 

ADD 4 TO ERCTFL MOVE 'E* TO ERRORSW 

GO TO R-61-9. 



FOUND ' REC-ID 



00156510 
00156520 
00156530 
00156540 
00156550 
00156560 
00156570 
00156580 
00156590 
00156600 
00156610 
00156620 
00156630 
00156640 
00156650 
00156660 
00156670 
00156680 
00156690 
00156700 
00156710 
00156720 
00156730 
00156740 
00156750 
00156760 
00156770 
00156780 
00156790 
00156800 
00156810 
00156820 
00156830 
00156840 
00156850 
00156860 
00156870 
00156880 
00156890 
00156900 
00156910 
00156920 
00156930 
00156940 
00156950 
00156960 
00156970 
00156980 
00156990 
00157000 
00157010 
00157020 
00157030 
00157040 
00157050 
00157060 
00157070 
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00229 00236o IF REC-ID lo NOT EQUAL TO VER-ID 00157080 

CQ230 00237w DISPLAY MSGriDR OISPLAY 'EXPECTED • VER-ID • FOUND • REC-ID 00157090 

00231 002380 AOD 1 TO ERCTFL MOVE 'E* TO ERRORSW 00157100 

00232 002390 MOVE REC-ID TO VER-ID. 00157110 
CC233 00240O ADD 1 TO VEK-NU. 00157120 
C0234 00241O R-61-9. 00157130 
O0235 002420 IF ERCTFL I;> GREATER THAN 3 00157140 
C0236 002430 GO TO BASE-70. 00157150 
00237 002440 SECTION-80 SECTION 80. 00157160 
C0238 00245O W-80-0. 00157170 
00239 00246o DISPLAY 'SECTION 80 WRITE'. 00157180 
GC240 002470 NOTE ENTERtti BV PERFORM FROM BASE-SECTION. 00157190 

00241 00248U PERFORM W-ol-0 THRU W-81-9 7 TIMES. 00157200 

00242 00249o PERFORM W-20^0 THRU W-20-9. 00157210 

00243 CC2500 W-80-9. 00157220 

00244 002510 EXIT. 00157230 
CC245 00252o W-81-0. 00157240 
CC246 00253U WRITE RECFDi FROM REC1 INVALID KEY 00157250 
0C247 002540 DISPLAY MSGriDR 00157260 
00248 00255o DISPLAY MSGcOX RECID 00157270 
0C249 002560 MOVE 'E' TO ERRORSW 00157280 

00250 002570 GO TO BASE-aO. 00157290 

00251 00258o ADO 0001 TO REC-NO. 00157300 

00252 00259O W-81-9. 00157310 

00253 002600 EXIT. 00157320 

00254 00261O R-80-0. 00157330 

00255 00262o DISPLAY 'SEcTION 80 READ'. 00157340 
C0256 O0263U NOTE ENTEREo BY PERFORM FROM BASE-50. 00157350 
C0257 002640 PERFORM R-8i.-0 THRU R-81-9 17 TIMES. 00157360 
CC258 002650 R-80-9. 00157370 
O0259 00266U EXIT. 00157380 
C0260 002670 R-81-0. 00157390 

00261 0C268O READ FILE-1 INTO REC1 AT END 00157400 

00262 O0269O DISPLAY MSGhDR DISPLAY MSGEOF 00157410 

00263 00270o AOD 4 TO ERLTFL MOVE »E' TO ERRORSW 00157420 
0C264 00271m GO TO R-81-y. 00157430 
00265 O0272O IF REC-ID la NjT EQUAL TO VER-ID 00157440 
0Q266 0C273J DISPLAY MSGHDR DISPLAY 'EXPECTED • VER-ID • FOUND « REC-ID 00157450 

00267 002740 ADD 1 TO ERoTFL MOVE 'E' TO ERRORSW 00157460 

00268 002750 MOVE REC-ID TO VER-ID. 00157470 
0026S 002760 ADD 1 TO VEK-NO. 00157480 
C027C 00277O R-81-8. 

00271 002780 IF ERCTFL Ii GREATER THAN 3 00157500 

CC272 0C279O GO TO BASE-70. 00157510 

00273 002800 R-81-9. 

0Q274 0C281U EXIT. 



INTRNL NAME 

DNM=2-<;34 

DNM=2-<:54 

DNM=2-^73 

DNM=2-<:93 

DNM=2-^09 

DNM=2-j2 5 

DNM=2-j41 

DNM=2-j57 

DNM=2-j73 

DNM=2-i90 

DNM=2-*09 

DNM=2-*25 

DNM=2-**1 

DNM= 2-^52 

DNM=2-*70 

DNM= 2-490 

DNM=3-o00 

DNM=3-0i6 



LVL 

FD 

01 

77 

77 

77 

77 

77 

77 

01 

02 

03 

03 

02 

66 

01 

02 

03 

03 



SOURCc NAME 

FILE-i 

RECFDi 

ERROKjW 

ERCTFL 

MSGHDK 

MSGEOA 

MSGEOF 

MSGNEl- 

REC1 

REC-lu 

REC-HU 

REC-Nu 

FILLEK 

RECID 

VER-RcC 

VER-Iu 

VER-HU 

VER-Nu 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE 


OCB=01 




DNM=2-234 






QSAM 


BL = 1 


000 


0NM=2-254 


OS 


83C 


DISP 


BL=2 


000 


DNM=2-273 


DS 


1C 


DISP 


BL=2 


001 


0NM=2-293 


DS 


2C 


DISP-NM 


BL=2 


003 


DNM= 2-309 


DS 


22C 


DISP 


BL=2 


019 


DNM=2-32 5 


DS 


36C 


DISP 


BL = 2 


030 


0NM=2-341 


DS 


37C 


DISP 


BL=2 


062 


DNM=2-357 


DS 


23C 


DISP 


BL=2 


080 


DNM=2-373 


DS 


0CL83 


GROUP 


BL=2 


080 


DNM=2-390 


DS 


0CL8 


GROUP 


BL=2 


080 


DNM= 2-409 


DS 


4C 


DISP 


BL = 2 


084 


DNM=2-425 


DS 


4C 


DISP-NM 


BL = 2 


088 


DNM= 2-441 


DS 


75 C 


DISP 


BL=2 


080 


DNM=2-452 


DS 


OCLP 


GROUP 


BL=2 


0D8 


DNM=2-470 


DS 


0CL8 


GROUP 


BL=2 


0D8 


DNM=2-*90 


OS 


0CL8 


GROUP 


BL = 2 


0D8 


DNM=3-000 


DS 


4: 


DISP 


BL=2 


OOC 


DNM=3-016 


DS 


4C 


OISP-NM 
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MEMORY MAP 



TGT 



00290 



SAVE AREA 

SWITCH 

TALLY 

SORT SAVE 

ENTRY-SAVE 

SORT CORE SIZE 

RET CODE 

SORT RET 

WORKING CELLS 

SORT FILE SIZE 

SORT MODE SIZE 

PGT-VN TBL 

TGT-VN TBL 

RESERVED 

LENGTH OF VN TBc 

LABEL RET 

RESERVED 

DBG R14SAVE 

COBOL INDICATOR 

A(INITl) 

DEBUG TABLE PTR 

SUBCOM PTR 

SORT-MESSAGE 

SYSOUT ODNAME 

RESERVED 

COBOL ID 

COMPILED POINTEk 

COUNT TABLE ADUkESS 

RESERVED 

DBG R11SAVE 

COUNT CHAIN ADOkESS 

PRBL1 CELL PTR 

RESERVED 

TA LENGTH 

RESERVED 

PCS LIT PTR 

DEBUGGING 

CD FOR INITIAL iNPUT 

OVERFLOW CELLS 

BL CELLS 

OECBADR CELLS 

FIB CELLS 

TEMP STORAGE 

TEMP STORAGE- 2 

TEMP STORAGE-3 

TEMP STORAGE-4 

BLL CELLS 

VLC CELLS 

SBL CELLS 

INDEX CELLS 

SUBADR CELLS 

GNCTL CELLS 

PFMCTL CELLS 

PFMSAV CELLS 

VN CELLS 

SAVE AREA =2 

SAVE AREA =3 

XSASW CELLS 

XSA CELLS 

PARAM CELLS 

RPTSAV AREA 

CHECKPT CTR 



00290 
002D8 
002DC 
002E0 
002E4 
002 E8 
002EC 
002EE 
002F0 
00420 
00424 
00428 
0042C 
00430 
00434 
00436 
00437 
00438 
0043C 
00440 
00444 
00448 
0044C 
00454 
00455 
00456 
00458 
0045C 
00460 
00468 
0046C 
00470 
00474 
00479 
0047C 
00484 
00488 
0048C 
00490 
00490 
00498 
00498 
0O4A0 
004A8 
004A8 
004A8 
004A8 
004BO 
004B0 
004B0 
004B0 
004B0 
004B0 
004D8 
00520 
005B0 
005B0 
005B8 
005B8 
005B8 
005B8 
0.0 5B 8 
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LITERAL POOL (HEX) 



0C6AS (LIT+O) 
006CO (LIT+2*) 



1C4C3C10 
08000000 



OuOOUOlC 
OuOBOOll 



00000000 
0007000D 



48140000 0004*000 OOIC0005 



DISPLAY LITERALS (BCD) 



0C6CC (LTL+3o) 
0C704 (LTL+9*) 
CC73C <LTL+l*ti) 
CC774 (LTL+2c4) 



'START TEST aEG-SAMPLEEND TEST SEG-SAMPLE UNSUCCESSFUL RU» 
'NENO TEST ScG-SAMPLE SUCCESSFUL RUNSECTION 20 WRITESECTI" 
•ON 20 READEAPECTED FOUND SECTION 30 WRITESECTIDN 30 REA" 
■DSECTION 40 WRITESECTION 40 READSECTION 60 WRITESECTION • 



0C7AC <LTL+2o0) »60 READSECTiON 80 WRITESECTION 80 READ* 



PGT 

DEBUG LINKAGE AkEA 
OVERFLOW CELLS 
VIRTUAL CELLS 
PROCEDURE NAME cELLS 
GENERATED NAME CELLS 
DCB ADDRESS CELcS 
VNI CELLS 
LITERALS 

DISPLAY LITERAL* 
PROCEDURE BLOCK CELLS 



0O5C0 

005C0 
005C0 
005C4 
005E4 
005E4 
00610 
00614 
006A8 
006CC 
007D4 



REGISTER ASSIGNMENT 



REG 6 
REG 7 



BL =2 
BL =1 



rtORKING-STORAuE STARTS AT LOCATION OOOAO FOR A LENGTH OF OOOEO. 

PFCCEDURE BcOCK ASSIGNMENT 
PBL = REG i.1 
PBL =1 aTARTS AT LOCATION 0007D8 STATEMENT 75 



SEGMENT = ROOT 
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**************#ROOT SEGMENT**** ************ 







0007D8 




14 


♦BASE-SECTION 








0007 D8 




15 


DISPLAY 


0007D8 








0007D8 


58 BO C 214 






G007DC 


58 FO C OOC 






0007EO 


05 IF 






0007E2 


0001 






0007E4 


10 






0007E5 


OOoOli) 






0O07E8 


OCuOOiOC 






0007EC 


OOuO 






0007EE 


FFl-F 


It 


OPEN 


O007FO 


58 10 C 050 



PN=01 



EQU 



000048 58 FO C 01C 
00004C 05 EF 
0OOD4E 47 FO B 57A 



oooooo 90 ec o ooc 

000004 18 50 

00C006 05 FO 

000008 45 80 F 010 

OOOOOC E2o5C7F0E2ClD4D7 

C00014 E5u2D9Fl 

000018 07 00 

00001A 98 9F F 024 

00001E 07 FF 

000020 96 02 1 034 

000024 07 FE 

000026 41 FO 001 

00002A 07 FE 

00002C 00O01&EE 

000030 00000000 

000034 OOuOOOOO 

000038 000005CO 

00003C 00o00290 

000040 00O00 7D8 

C00044 000016AE 
000048 

000084 OOoOOOOO 

000088 FlF74bF4F64BF3F6 

000090 Clc4C74040F46B40 

0CC098 FU-9F7F6 



PN=02 


EQU 


* 




START 


EQU 


* 






L 


11,214(0,12) 


PBL = 1 




L 


15,00C(O,12) 


V(ILBODSSO) 




BALR 


1,15 






DC 


X'OOOl' 






DC 


X'lO' 






DC 


X'000015' 






DC 


X'OCOOOIOC 


LIT+36 




DC 


X'OOOO' 






DC 


X'FFFF* 






L 


1,050(0,12) 


DCB=1 




L 


15,01C(0,12) 


V(ILBOGDOl) 




BALR 


14,15 






BC 


15,57A(0,11) 


PN=016 


INIT1 


STM 


14,12,00C(13) 






LR 


5,13 






BALR 


15,0 






BAL 


8,010(0,15) 






DC 


X'E2C5C7F0E2C1D4D7' 






DC 


X , E5E2D9F1« 






BCR 


0,0 






LM 


9,15,024(15) 






BCR 


15,15 






01 


034( 1) ,X , 02« 






BCR 


15,14 






LA 


15,001(0,0) 






BCR 


15,14 






ADCON 


L4UNIT3) 






AOCON 


L4(INIT1) 






ADCON 


L4(INIT1) 






ADCON 


L4(PGT) 






ADCON 


L4(TGT) 






ADCON 


L4( START) 






ADCON 


L4UNIT2) 






OS 


15F 






DC 


X'OOOOOOOO' 






DC 


X'F1F74BF4F64BF3F6' 






DC 


X«C1E4C74040F46B40' 






OC 


X'F1F9F7F6« 





Figure 154. Sample Segmentation Program (Part 8 of 14) 
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********* ******S£GMEimT OF PTY 30**************** 



133 



134 



13! 



*SECTlON-30 



137 



*W-30-0 



DISPLAY 



PERFORM 



58 FO C 00C 
05 IF 



000052 

000052 

000052 

000056 

000058 OOul 

00005A 10 

00005B OOuOlO 

00005E 0Cu00196 

000062 OOwiO 

000D64 FFFF 

000066 02 03 D 268 2B8 



000F90 58 FO C 01C 
000F94 05 EF 
OO0F96 47 FO 6 7C2 



PN=016 


EQU 


* 




PN=017 


EQU 


* 






L 


15,00C(0fl2J 


V(ILBODSSO) 




BALR 


ltl5 






DC 


X'OOOl' 






OC 


X'10' 






DC 


X'000010' 






OC 


X'0C000196' 


LIT+174 




OC 


X'OOOO' 






OC 


X'FFFF' 






MVC 


268(4,13) ,2B8(13J 


PSV=9 




L 


15,01C(0,12) 


V(ILBOGDOl) 




BALR 


14,15 






BC 


15,7C2(0,11) 


PN=024 



VN=06 



***************SEGMEwT OF PTY 40**************** 



167 



166 



169 



171 



*SECT10N-40 
















000F9A 




PN=024 


EQU 


* 




*W-40-0 
















000F9A 




PN=025 


EQU 


* 




DISPLAY 


000F9A 


58 FO C OOC 




L 


15,00C(0,12) 


V(ILBODSSO) 




OO0F9E 


05 IF 




BALR 


1,15 






OOOFAO 


OOul 




DC 


X'OOOl' 






000FA2 


10 




DC 


X'10' 






000FA3 


OOuOlO 




DC 


X'000010' 






000FA6 


OCJ001B5 




DC 


X'0C0001B5' 


LIT+205 




OOOFAA 


OOuO 




DC 


X'OOOO' 






OOOFAC 


FFFF 




DC 


X'FFFF' 




PERFORM 


OOOFAE 

• 


02 03 270 D 200 




MVC 


270(4,131,200(13) 


PSV=11 




• 

0011F6 


58 FO C 01C 




L 


15,01C(0,12) 


V(ILBOGDOl) 




0011FA 


05 EF 




BALR 


14,15 






0011FC 


47 FO B A28 




BC 


15,A28(0,1U 


PN=033 



VN=09 



Figure 154. Sample segmentation Prograa (Part 9 of 14) 
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***************5EGMENT OF PTY 60**************** 



203 



204 



2C5 



2C7 



*SECTiON-60 


















001200 




PN=033 


EQU 


* 






*W-60-0 


















0012C0 




PN=034 


EQU 


* 






DISPLAY 


001200 


58 FO C OOC 




L 


15tOOC(0,12) 


V(ILBODSSO) 






001204 


05 IF 




BALR 


1,15 








001206 


OOul 




DC 


X'OOOl' 








001208 


10 




OC 


X'10' 








001209 


OOuOlO 




DC 


X'OOOOIO" 








0012 OC 


0CUOO1D4 




DC 


X , OC0001D4' 


LIT+236 






001210 


OOuO 




DC 


X'OOOO* 








001212 


FFFF 




DC 


X'FFFF" 






PERFuRM 


001214 

• 


D2 03 27C 2F0 




MVC 


27C(4,13),2F0(13) 


PSV=14 


VN=013 




• 

00144A 


58 FO C 01C 




L 


15,01C(0,12) 


V(ILBOBDOl) 






00144E 


05 EF 




BALR 


14,15 








001450 


47 FO B C7C 




BC 


15,C7C(0,11) 


PN=041 





*** v ***********sEGMEttT q F p-j-y so**************** 



237 



238 



239 



241 



♦SECTION-80 


001454 










♦W-60-0 


001454 










DISPLAY 


01454 


58 


FO 


C 


OOC 




001458 


05 


IF 








00145A 


OOul 








00145C 


10 










00145D 


OOuOlO 






001460 


0Cu001F3 




001464 


OOuO 








001466 


FFFF 






PERFuRM 


001468 

• 


D2 


03 


D 


284 D 




• 

001766 


05 


10 








001768 


58 


00 


8 


000 




00176C 


12 


00 








00176E 


47 


80 


1 


010 




001772 


IE 


OB 








001774 


50 


00 


8 


000 




001778 


87 


86 


1 


000 




00177C 


58 


60 


D 


204 




001780 


58 


70 


D 


200 




001784 


D2 


8F 


D 


290 C 




00178A 


58 


EO 


D 


054 




00178E 


07 


FE 







308 



054 



PN=041 


EQU 


* 




PN=042 


EQU 


* 






L 


15,00C(0,12) 


V(ILBODSSO) 




BALR 


1,15 






DC 


X'OOOl' 






DC 


X'10* 






DC 


X'OOOOIO' 






DC 


X»0C0001F3« 


LIT+267 




DC 


X«0000« 






DC 


X'FFFF' 






MVC 


284(4,13), 308(13) 


PSV=16 




BALR 


1,0 






L 


0,000(0,8) 






LTR 


0,0 






BC 


8,010(0,1) 






ALR 


0,11 






ST 


0,000(0,8) 






BXLE 


8,6,000(1) 






L 


6,204(0,13) 


BL =2 




L 


7,200(0,13) 


BL =1 




MVC 


290(144, 13), 054(12) 


VN=01 




L 


14,054(0,13) 






BCR 


15,14 





VN=016 



VNI = 1 



Figure 154. Sample Segmentation Program (Part 10 of 14) 
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♦STATISTICS* 



SOURCE RECORD* 



274 



DATA OIVISION STATEMENTS = 



18 



PROCEDURE DIVISION STATEMENTS = 



165 



♦OPTIONS IN EFFECT* 
♦OPTIONS IN EFFECT* 
♦GPTIONS IN EFFECT* 
*OPTIONS IN EFFECT* 
♦OPTIONS IN EFFECT* 
♦OPTIONS IN EFFECT^ 



SIZE = 131072 BUF = 12288 LINECNT = 57 SPACE1, FLAGW, SEQ, SOURCE 

OMAP, PMAP, NOCLIST, NOSUPMAP, NOXREF, SXREF, LOADt NODECK, APOST, NOTRUNC, NOFLOW 

NOTERM, NONUMf NOBATCH, NONAMEt COMPILE=01, NOSTATE, NORESIOENTt NODYNAM, NDLIB, NOSYNTAX 
OPTIMIZE, NOSYMDMP, NOTEST, VERB, ZWB, SYST, NOENDJOB, NOLVL 

NOLST , NUFDECK,NOCDECK, LCOL2, L120, DUMP , NOAOV , NOPRINT, 

NOCOUNT, NOVBSUM, NOVBREF, LANGLVK2) 



CROSS-REFERENCE DICTIONARY 



CATA NAMES 

ERCTFL 

EfifiOKSW 

FILE-1 

MSGEOF 
MSGEOX 
MSGFOR 

MSGNEF 
REC-HD 
REC-ID 

R EC-NO 
RECFOl 

RECIO 
REC1 

VER-hD 
VER-ID 

VEP-NO 
VER-kEC 



DEFN 


REFERENCE 














000056 


000123 


000127 


000131 


000157 


000161 


000165 


000193 


000197 




000231 


000235 


000263 


000267 


000271 








00005 5 


000090 


000094 


000109 


000123 


000127 


000144 


000157 


000161 




000197 


000214 


000227 


000231 


000249 


000263 


000267 




U00046 


000076 


000082 


000083 


000088 


000092 


000106 


000121 


000141 




000191 


000211 


000225 


000246 


000261 








000060 


000122 


000156 


000192 


000226 


000262 








000058 


000108 


000143 


000177 


000213 


000248 








000057 


000089 


000107 


000122 


000126 


000142 


000156 


000160 


000176 




000212 


000226 


000230 


000247 


000262 


000266 






000062 


000089 
















000065 


















000064 


000125 


000126 


000128 


000159 


000160 


000162 


000195 


000196 




000230 


000232 


000265 


000266 


000268 








000066 


000111 


000146 


000180 


000216 


000251 








000053 


000088 
000261 


000106 


000121 


000141 


000155 


000175 


000191 


000211 


000068 


000108 


000143 


000177 


000213 


000248 








000063 


000088 
000261 


000106 


000121 


000141 


000155 


000175 


000191 


000211 


000071 


















000070 


000125 


000126 


000128 


000159 


000160 


000162 


000195 


000196 




000230 


000232 


000265 


000266 


000268 








000072 


000129 


000163 


000199 


000233 


000269 








000069 



















000201 000227 

000178 000193 

000155 000175 

000192 000196 

000198 000229 

000225 D00245 

000225 0002*6 

000198 000229 



Figure 154. Saaple Segmentation Program (Part 11 of 14) 
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PROCEDURE NAMES 



DEFN 



REFERENCE 



BASE-SECTION 

eASE-50 

BASE-60 

EASE-70 

eASE-90 

R-2C-0 

B-20-9 

R-21-0 

R-21-9 

R-30-0 

R-31-0 

R-31-9 

R-40-0 

R-40-9 

R-41-0 

R-41-9 

R-60-0 

R-61-0 

R-41-9 

R-80-0 

R-8C-9 

R-81-0 

ft- 8 1-8 

R-81-9 

SECTION-20 

SECT10N-30 

SECTION-40 

SECTION-60 

SECTION-80 

*-2C-0 

W-20-9 

H-21-0 

h-21-9 

k-30-0 

W-3C-9 

W-31-0 

h-il-9 

W-40-0 

W-40-9 

h-41-0 

W-41-9 

h-60-0 

h-6C-9 

W-61-0 

h-61-9 

W-8C-0 

K-80-9 

W-81-0 

h-81-9 



000074 
000081 
000086 
000091 
000093 
000114 
000118 
000120 
000130 
000149 
000154 
000164 
000183 
000188 
000190 
000200 
000219 
000224 
000234 
000254 
000258 
000260 
000270 
000273 
000098 
000133 
000167 
000203 
000237 
U00099 
000103 
000105 
000112 
000134 
000138 
000140 
000147 
000168 
000172 
U00174 
000181 
000204 
000208 
000210 
000217 
000238 
000243 
000245 
000252 



000110 000145 000179 000215 000250 

000153 

000088 000132 000166 000202 000236 000272 

000187 

000187 

000117 

000117 000124 

000223 

000152 

000152 000158 

000087 

000087 

000186 

000194 

000085 

000222 

000222 000228 

000084 

000084 

000257 

000257 000264 

000132 
000166 
000202 
000236 
0002*2 
000242 
000102 
000102 
000078 
000078 
000137 
000137 
000080 
000080 
000171 
000171 
000079 
000079 
000207 
000207 
000077 
000077 
000241 
000241 



Figure 154. Sample Segmentation Program {Part 12 of 14) 
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F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED LIST.XREF 
OEFAULT OPTION(S) USED - S IZE= ( 196608, 65536) 
IEWO0O0 ENTRY SEGOSAMP 

1EW0201 



CROSS REFERENCE TABLE 



CONTROL SECTION 



NAME 



ORIGIN LENGTH SEG. NO. 



SEGOSAMP 


00 


1790 


ILBOCOMO* 


1790 


169 


ueooss * 


1900 


40A 


ILEGEXT * 


1D10 


50 


IL80GD0 * 


1D60 


114 


ILBOQIO * 


1E78 


56E 


ILBOSRV * 


23E8 


48E 



ILBOSYN * 2878 440 

ILBOBEG * 2CB8 128 

ILBOCHN * 2DE0 1 BO 

UeOCMM * 2F90 38B 

ILBOMSG * 3320 F2 



ENTRY 
















NAME 


LOCATION 


NAME 


LOCATION 


NAME 


LOCATION 


NAME 


LOCATIO 


ILBOCOM 


1790 














ILBODSSO 


1902 














ILBOEXTO 


1D12 


ILB0EXT1 


1D16 










ILBOGDOO 


1062 


ILB0GD01 


1D66 


ILB0G002 


1D6A 






ILBOQIOO 


1E7A 














ILBOSRVO 


23F2 


ILB0SR5 


23F2 


ILB0SR3 


23F2 


ILBOSR 


23F2 


ILB0SRV1 


23F6 


ILB0STP1 


23F6 


ILBOST 


23FA 


ILBOSTPO 


23FA 


ILBOSYNO 


2 87A 


ILB0SYN1 


287E 


ILB0SYN2 


2882 


ILB0SYN3 


2686 


ILB0SYN4 


288A 


ILB0SYN5 


288E 










IL80BEG0 


2CBA 














ILBOCHNO 


2DE2 














ILBOCMMO 


2F92 


ILB0CMM1 


2F96 










ILBOMSGO 


3322 















LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 



LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 



5C4 


ILBCSRVO 


ILBOSRV ] 


L 5C8 


5CC 


ILBODSSO 


ILBODSS ] 


L 500 


5D4 


ILBOEXTO 


ILBOEXT ] 


L 5D8 


5 DC 


ILBCGD01 


ILBOGDO ] 


L 5E0 


448 


ILBOCOMO 


ILBOCOMO ] 


L 2738 


273C 


ILBOCMMO 


ILBOCMM ] 


L 2740 


2744 


ILBOMSGO 


ILBOMSG ] 


L 2748 


2C40 


ILBOCHNO 


ILBOCHN ] 




EN7BY AOORESS 


00 







ILB0SR5 

ILB0SYM1 

ILBOQIOO 

ILB0SRV1 

ILBOCOM 

ILBOBEGO 

ILB0SND2 



ILBOSRV 
ILBOSYN 
ILBOQIO 
ILBOSRV 
ILBOCOMO 
ILBOBEG 
$UNRESOLVEDIW) 



TCTAL LENGTH 3418 
****G0 DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 
ACIHORIZATION CODE IS 0. 



Figure 154. sample Segmentation Program (Part 13 of 14) 
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START TEST SEG-SAMPLE 

SECTION 80 WRITE 

SECTION 20 WRITE 

SECTION 30 WRITE 

SECTION 60 WRITE 

SECTION HO WRITE 

SECTION 80 READ 

SECTION 60 READ 

SECTION 30 READ 

SECTION 40 READ 

SECTION 20 READ 

END TEST SEG-SAMPLE SUCCESSFUL RUN 



Figure 154. Sample Segmentation Program (Part 14 of 14) 
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USING THE CHECKPQJJT/RESTART FEATURE 



The IBH Operating system Checkpoint/ 
Restart feature is designed to be used with 
programs running for an extended period of 
time when interruptions may halt processing 
before the end of the job, The feature may 
be used when the programmer anticipates any 
type of interruption, i.e., interruptions 
caused by machine malfunctions, 
input/output errors, or intentional 
operator intervention, etc. It allows the 
interrupted program to be restarted at the 
job step or at a point other than at the 
beginning of the job step. The feature 
consists of two routines: Checkpoint and 
Restart. 

The Checkpoint routine is invoked from 
the COBOL load module containing the user's 
program. It moves information stored in 
registers and in main storage into a 
checkpoint record at user-designated points 
during execution of the program. The 
programmer specifies these points using the 
COBOL RERUN clause in the Environment 
Division. 



a specified nu 
are processed 
reached while 
programmer dec 
checkpoints ta 
clause. The c 
on the checkpo 
DD statement a 
system-name in 
statement desc 
set and a chec 



mber of records on that file 
or when end of volume is 
processing a file. The 
ides when he wants the 
ken as he codes the RERUN 
heckpoint records are written 
int data set defined by the 
nd are referenced by 

the RERUN clause. The DD 
ribes both a checkpoint data 
kpoint method. 



Checkpoint records on ASCII-collated 
sorts can be taken, but the system-name 
indicating the checkpoint data set must not 
specify an ASCII file. 



Note; If checkpoints are to be taken 
during a sorting operation, a DD statement 
called SORTCKPT must be added when the 
program is executed. 



The Restart routine r 

Re 



interrupted 
the beginnin 
checkpoint i 
written. Th 
contain all 
restart the 
initiated at 
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later time c 
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after the in 
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onvenient to 

estart. 



estarts an 

start can occur at 

tep, or at a 

nt record has been 

record will 
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start can be 
ter the program was 

may be run 
terrupt has 
c restart, or at a 

the programmer, as 



The COBOL RERUN clause provides linkage 
to the system checkpoint routine. Hence, 
any cautions and restrictions on the use of 
the system Checkpoint/Restart feature also 
apply to the use of the RERUN clause. 

The Checkpoint/Restart feature is fully 
described in the publication OS/VS 
Ch eckpoint/Restart . 



Ch ec kgo|nt {le t ho ds 



The programmer may elect to store single 
or multiple checkpoints. 



Single: Only one checkpoint record exists 
at any given time. After the first 
checkpoint record is written, any 
succeeding checkpoint record overlays the 
previous one. This method is acceptable 
for most programs. It offers the advantage 
of saving space on the checkpoint data set 
and allows the programmer to restart his 
program at the latest checkpoint. 



Mu ltiple (multiple contig uous),, : 
Checkpoints are recorded and numbered 
sequentially. Each checkpoint is saved. 
This method is used when the programmer may 
wish to restart a program at a checkpoint 
other than the latest one taken. 



TAKING A CHECKPOINT 



In order to initiate a checkpoint, the 
programmer uses job control statements and 
the COBOL RERUN clause. The programmer 
associates each RERUN clause with a 
particular COBOL file. The RERUN clause 
indicates that a checkpoint record is to be 
written onto a checkpoint data set whenever 



DD STATEMENT FORMATS 



The programmer records checkpoints on 
tape or direct access devices. Following 
are the DD formats to define checkpoint 
data sets. 
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For Tape: 



j//ddname DD DSNAME=data-set-name, Xj 

j// VOLUME=SER=volser, X] 

j// UNIT=deviceno„ Xj 

I ( new) I 

|// DISP=( < > „PASS), X| 

1 (mod) I 

j // DCB= ( TRTCH=C ) „ LABEL= { „ NL) | 

L J 



Note: The DCB parameter is necessary only 
for 7-track tape conversion; for 9-track 
tape it is not used. 



MOD 



NEH 



PASS 



is specified for the multiple 
contiguous checkpoint method. 



is specified for the single checkpoint 
raethod- 



is specified in order to prevent 
deletion of the data set at the 
successful completion of the job step, 
unless it is the last step in the job. 
If it is the last step, the data set 
will be deleted with PASS. 



KEEP 



For Mass Storage: 



j //ddname DD DSNAME=data-set-name, X] 

j// VOLUME=( PRIVATE, RETAIN, X] 

j// SER=volser)„ X| 

|// UNIT=deviceno # X| 

j// SPACE= (subparts) , xj 

' NEW) ] 

j// DISP={ { \ ,PASS,KEEP) X| 

MOD \ I 



is specified in order to keep the data 
set if the job step abnormally 
terminated and may be restarted. 



The following listings are examples that 
define checkpoint data sets. 



• To write single checkpoint records 
using tape: 



where: 



ddname 

is the same as the ddname portion of 
the system-name used in the COBOL 
HERON clause to provide a link to the 
DD statement. 



//CHECKPT DD DSNAME=CHECK 1 , X 

// VOLUME=SE8=ND003, X 

// UNIT=2400,DISP=(NE»,KEEP) , X 

// LABEL=(,NL) 



ENVIRONMENT DIVISION. 



data-set-name 

is the name given to each particular 
data iet used to write checkpoint 
records. This name identifies the 
checkpoint data set to the Restart 
procedure (see "Restarting a 
Program") . 



volser 

identifies the volume by serial 
number. 



deviceno 

identifies the device. For tape it 
indicates the device number for 
7-track or 9-track tape. For mass 
storage, it indicates the device 
number for disk or drum. 



RERUN ON UT-2400-S-CHECKPT EVERY 
5000 RECORDS OF ACCT-FILE. 



• To write single checkpoint records 
using disk (note that more than one 
data set may share the same 
external-name) : 

//CHEK DD DSNAHE=CHECK2, X 

// VOL0ME= (PRIVATE, RETAIH, X 

// SER=DB0 30, X 

// 0NIT=2314,DISP= (NEW, KEEP) , X 

// SPACE= (TRK,300) 



ENVIRONMENT DIVISION. 



subparms 

specifies the amount of track space 
needed for the data set. 



RERUN ON UT-2314-S-CHEK EVERY 
20000 RECORDS OF PAYCODE. 
RERUN ON UT-2314-S-CHEK EVERY 
30000 RECORD OF IN-FILE. 
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• To write multiple contiguous checkpoint 
records (on tape) : 

//CHEKPT DD DSNAME=CHECK3, X 

// V0LUME=SEB=111111, X 

// ONIT=2400,DISP= (HOD, PASS), X 

// LABEL=(,NL) 



ENVIRONMENT DIVISION. 



[IHJ004I jobname (ddnarae,unit,volser) 
CHKPT checkid ] 

where checkid is the identification name of 
the checkpoint taken. Checkid is assigned 
by the control program as an 8-digit 
number. The first digit is the letter C, 
followed by a decimal number indicating the 
checkpoint. For example, checkid C0000004 
indicates the fourth checkpoint taken in 
the job step. 



RERUN ON UT-2400-S-CHEKPT EVERY 
10000 RECORDS OF PAY-FILE. 

Note: A checkpoint data set must have 
sequential or partitioned organization. 



DESIGNING A CHECKPOINT 



The programmer should design his 
checkpoints at critical points in his 
program so that data may be easily 
reconstructed. For example, in a program 
using mass storage files, changes to 
records in these files will replace 
previous information; thus the programmer 
should be sure he can identify previously 
processed records. Assume that a mass 
storage file contains loan records that 
periodically are updated for interest due. 
If a checkpoint is taken, records are 
updated, and then the proqram is 
interrupted, the records updated after the 
last checkpoint will be updated a second 
time in error unless the programmer 
controls this condition. (He may set up a 
date field for each record and update the 
date each time the record is processed. 
Then, after the restart, by investigating 
the date field he can determine whether or 
not the record was previously processed.) 
For efficient repositioning of a print 
file, the programmer should take 
checkpoints on that file only after 
printing the last line of a page. At 
system generation time, those ABEND codes 
for which the checkpoints are desired 
(DEFAULT) must be specified. 



MESSAGES GENERATED DURING CHECKPOINT 



The system checkpoint routine advises 
the operator of the status of the 
checkpoints taken by displaying informative 
messages on the console. 

When a checkpoint has been successfully 
completed, the following message will be 
displayed: 



The system Restart routine retrieves the 
information recorded in a checkpoint 
record, restores the contents of main 
storage and all registers. 

The Restart routine can be initiated in 
one of two ways: 

• Automatically at the time an 
interruption stopped the program 

• At a later time as a deferred restart 

The type of restart is determined by the RD 
parameter of the job control language. 



RD Parameter 



The RD parameter may appear on either 
the JOB or the EXEC statement. If coded on 
the JOB statement, the parameter overrides 
any RD parameters on the EXEC statement. 
If the programmer wishes to have his 
program restart automatically, he codes 
RD=R or RD=RNC. RD=R indicates that 
restart is to occur at the latest 
checkpoint. The programmer should specify 
the RERUN clause for at least one data set 
in his program in order to record 
checkpoints. If no checkpoint is taken 
prior to interruption, restart occurs at 
the beginning of the job step. RD=RNC 
indicates that no checkpoint is to be 
written and any restart will occur at the 
beginning of the job step. In this case, 
RERUN clauses are unnecessary; if any are 
present, they are ignored. If the RD 
parameter is omitted, the CHKPT macro 
instruction remains activated, and 
checkpoints may be taken during processing. 
If an interrupt occurs after the first 
checkpoint, automatic restart will occur. 
Thus, if the user does not want automatic 
restart, he should always include the RD 
parameter with a code of either RD=NR or 
RD=NC, both of which suppress the automatic 
restart procedure. 
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If the programmer wishes his program to 
be restarted on a deferred basis, he should 
code the BD parameter as RD=NR. This form 
of the parameter suppresses automatic 
restart but allows a checkpoint record to 
be written provided a REROH clause has been 
specified. At restart time, the programmer 
may choose to restart his program at a 
checkpoint other than at the beginning of 
the job step. 



The programmer may also elect to 
suppress both restart and writing 
checkpoints. By coding RD=NC, the 
programmer, in effect, is ignoring the 
features of the Check point /Restart 
facility. 



Whenever automatic restart is to occur, 
the system will reposition all devices 
except unit-record machines. 



r ed R estart 



Deferred restart may occur at any 
checkpoint, not necessarily the latest one 
taken. 



The programmer requests a deferred 
restart by means of the RESTART parameter 
on the JOB card and a SYSCHK DD statement 
to identify the checkpoint data set. The 
formats for these statements are as 
follows: 



Automatic Restar t 



Automatic Restart occurs only at the 
latest checkpoint taken. (If no checkpoint 
was taken before interruption, Automatic 
Restart occurs at the beginning of the job 
step) . 



In order to restart automatically, a 
program must satisfy the following 
conditions. 

• A program must request restart by using 
the RD parameter or by taking a 
checkpoint. 

• An ABEND that terminated the job must 
return a code eligible to cause 
restart. (For further discussion on 
this requirement, see the publication 
QS/VS Checkpoint /Resta rt. ) 

• The operator authorizes the restart, 
with the following procedure: 

The system displays the following 
message to request authorization of the 
restarts 



//jobname JOB , MSGLEVEL=1, X 

// RESTAHT= (request, [checkid]) 

//SYSCHK DD DSNAME=data- set-name, X 

// DISP=OLD,DNIT-deviceno, X 

// VOLUME=SER=volser 



where: 

HSGLEVEL=1 (or HSGLEVEL= (1 , y) where y_ is 
either or 1) 
is required. 

RESTART= (request, [ checkid]) 

identifies the particular checkpoint 
at which restart is to occur. Request 
may take one of the followinq forms: 

* to indicate restart at the beginning 
of the job 

stepname to indicate restart at the 
beginning of a job step 

stepname. procstep to indicate restart 
at a procedure step within the 
jobstep 

checkid 

identifies the checkpoint where 
restart is to occur. 



XXIEF225D SHOULD 

jobname. stepname. procstep 
RESTART [checkid] 

The operator must reply in the 
following form: 

REPLY XX, » {YES J HOI HOLD} • 

where YES authorizes restart, MO 
prevents restart, and HOLD defers 
restart until the operator issues a 
RELEASE command, at which time restart 
will occur. 



SYSCHK 

is the DDNAHE used to identify a 
checkpoint data set to the control 
program. The SYSCHK DD statement must 
immediately precede the first EXEC 
statement of the resubmitted job, and 
must follow any JOBLIB statement. 



data- set-name 

must be the same name that was used 

when the checkpoint was taken. It 

identifies the checkpoint data set 
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deviceno and volser 

identify the device number and the 
volume serial number containing the 
checkpoint data set. 



As an example illustrating the use of 
these job control statements, a restart of 
the GO step of a COBUCLG procedure, at 
checkpoint identifier (CHECKID) C0000003, 
might appear as follows: 

//jobname JOB ,HSGLEVEL= 1, ] 



// RESTART= 

// {stepname. GO,C000000 3) 

//SYSCHK DD DSNAME=CHEKPT, 

// DISP=OLD,UNIT=2400, 

// VOLUME=SER=111111 



following the restart step if they 
contain the form stepname or 
stepname. procstep referring to a step 
preceding the restart step. However, 
if these parameters are used, the 
preceding step referred to must be 
specified in the resubmitted deck. 

When a deferred restart has been 
successfully completed, the system will 
display the following message on the 
console: 

IHJ008I jobname RESTARTED 

Control is then given to the user's prograi 
that executes in a normal manner. 



{DD statements similar to original deckj 



The Restart routine uses information 
from DD statements in the resubmitted job 
to reset files for use after restart; 
therefore, care should be taken with any DD 
statements that may affect the execution of 
the restarted job step. Attention should 
be paid to the following: 

• During the original execution, a data 
set meant to be deleted at the end of a 
job step should conditionally be 
defined as PASS rather than DELETE in 
order to be available if an 
interruption forces a restart. If the 
restart is at the beginning of a step, 
a data set created in the original 
execution {defined as NEW on a DD 
statement) must be scratched prior to 
the restart. If the data set is not 
deleted, the DD statement must be 
changed to define it as OLD. 

• At restart time, input data sets on 
cards should be positioned as they were 
at the time of the checkpoint. Input 
data sets on tape or direct access 
devices will be automatically 
repositioned by the system. 

» At restart time, the EXEC statement 
parameters PGH and COND, and the DD 
statement parameters S0BALLOC and 
V0LU«E=REF must not be used in steps 



CHECKPOINT/RESTART DATA SETS 



If the RERUN clause was executed during 
the original execution of the processing 
program, checkpoint entries were written on 
a checkpoint data set. To resubmit a job 
for restart when execution is to be resumed 
at a particular checkpoint, an additional 
DD statement must be included. This DD 
statement describes the data set on which 
the checkpoint entry was written and it 
must have the ddname SYSCHK. The SYSCHK DD 
statement must immediately precede the 
first EXEC statement of the resubmitted job 
and must follow the DD statement named 
JOSLIB, if one is present. 

For both deferred and automatic 
checkpoint/restart, if Direct SYSO0T Writer 
for the restarted job was active at the 
time the checkpoint was was taken, it must 
be available for the job to restart. For 
further information, see the publication 
QS/ys_Checkpoint/Restart. 

If the checkpoint data set is 
multivolume, the sequence number of the 
volume on which the checkpoint entry was 
written must be included in the VOLUME 
parameter. If the checkpoint data set is 
on a 7-track magnetic tape with nonstandard 
labels or no labels, the SYSCHK DD 
statement must contain DCB= (T8TCH=C,.. .) . 

Figure 155 illustrates a sequence of 
control statements for restarting a job. 



t — — 

I //PAY ROLL 


JOB 


MSGLEVEL=1,SEGION=80K,SESTART= (STEP1 ,CHECKPT4) | 


| //JOB LIB 


DD 


DSNAME=PRIV.LIB3,DISP=0LD | 


! //SYSCHK 


DD 


DSNAME=CHKPTLIB,UNIT=2314,VOL=SER=456789, X | 


\// 




DISP= {OLD, KEEP) f 


J //STEP 1 

i — _ . 


EXEC 


PGH=PRQG4,TIHE=5 | 

_ _ — _ - . _— ., i 



Figure 155. Restarting a Job at a Specific Checkpoint Step 
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If a SYSCHK DD statement is present in a 
job and the JOB statement does not contain 
the BESTABT parameter, the SYSCHK DD 
statement is ignored. If a BEST AST 
parameter without the CHECKID subparameter 
(as in Figure 157) is included in a job, a 
SYSCHK DD statement must not appear before 
the first EXEC statement for a job. 

Figure 156 illustrates the use of the RD 
parameter. Here, the BD parameter requests 
step restart for any abnormally terminated 
job step. The DD statement DDCKPNT defines 
a checkpoint data set. For this step, once 
a RERUN clause is executed, only automatic 
checkpoint restart can occur, unless a 
CHKPT cancel is issued. 

Figure 157 illustrates those 
modifications that might be made to control 
statements before resubmitting the job for 
step restart. The job name has been 
changed to distinguish the original job 



from the restarted job. The BESTART 
parameter has been added to the JOB 
statement and indicates that restart is to 
begin with the first job step. The DD 
statement HORK originally assigned a 
conditional disposition of KEEP for this 
data set. If this step did not abnormally 
terminate during the original execution, 
the data set was deleted and no 
modifications need be made to this 
statement. If the step did abnormally 
terminate, the data set was kept. In this 
case, define a new data set as shown in 
Figure 157, or change the data set's status 
to OLD before resubmitting the job. A new 
data set has also been defined as the 
checkpoint data set. 



Figure 158 illustrates those 
modifications that might be made to control 
statements before resubmitting the job for 
checkpoint restart. 



J //J 1234 


JOB 


I//S1 


EXEC 


J//INDATA 


DD 


1// 




I //REPORT 


DD 


I//WOBK 


DD 


!// 




| //DDCKPNT 


DD 


i 





386,SHITH # HSGLEVEL=1/BD=fi 

HYPROG 

DSNAHE=INVENT,UNIT=2400,DISP=OLD, VOL0ME=SER=9 1468, X 

LABEL=RETPD=14 

SYSOUT=A 

DSNAHE=T91468,DISP=(, # KEEP) ,UNIT=SYSDA, X 

SPACE=(3000, (5000,500)) ,VOLUHE= (PRIVATE, RETAIN,, 6) 

UNIT=2400,DISP=(MOD,PASS, CATLG) ,DSNAHE=C91 468 ,LABEL= (,NL) 



Figure 156. Using the BD Parameter 



I //J 34 12 


JOB 


I//S1 


EXEC 


I//INDATA 


DD 


I// 




I //REPORT 


DD 


J //WORK 


DD 


1// 




I//DDCHKPNT 


DD 


i— _ 





386, SHITH,MSGLEVEL=1 # BD=H, BEST ART=* 

MYPBOG 

DSNAME=INVENT,UNIT=2400,DISP=OLD,VOLUaE=SER=91468, X 

LABEL=RETPD=14 

SYSO0T=A 

DSNAME=S91468,DISP=(,,KE£P) ,UNIT=SYSDA, X 

SPACE=(3000, (5000,500)) ,VQLUME= (PRIVATE , RETAIN, , 6) 

UNIT=2400,DISP= (HOD, PASS, CATLG) ,DSNAHE=R9 1468 ,LABEL= (, NX) 



Figure 157. Modifying Control Statements Before Resubmitting for step Restart 
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I//J3412 


JOB 


I//SYSCHK 


DD 


I//S1 


EXEC 


J//INDATA 


DD 


1// 




I //REPORT 


DD 


J//BOBK 


DD 


f// 




J//DDCKPNT 


DD 


1// 




Figure 158. 


ModL 



386, SMITH, HSGLEVEL=1,RD=R,RESTART=(*,C0000002) 

DSNAMB=C91468,DISP=OLD 

MYPROG 

DSNAME=IHyENT,UNIT=2400,DISP=OI.D, 

VOLUHE=SER=91468,LABEL=RETPD=14 

SYSO0T=A 

DSHAME=T91468,DISP=(, ,KEEP) , ONIT=S¥SD A, 

SPACE={3000, (5000,500)) ,VOLUME= (PRIVATE, RETAIN, , 6) 

UNIT=2400,DISP= (MOD, KEEP, GATLG) ,DSNAME=C9 1468, 

LABEL=(,HL) 



Modifying control Statements Before Resubmitting for Checkpoint Restart 



The job name has been 
distinguish the original 
restarted job. The REST 
been added to the JOB st 
indicates that restart i 
first step at the checkp 
C0000002. The DD states 
originally assigned a co 
disposition of CATLG for 
data set. If this step 
terminate during the ori 
the data set was kept. 
SYSCHK DD statement must 
information necessary to 



changed to 

job from the 
ART parameter has 
atement and 
s to begin with the 
oint entry named 
ent DDCKPNT 
nditional 

the checkpoint 
did not abnormally 
ginal execution. 
In this case, the 

contain all of the 

retrieve the 



checkpoint data set. If the job did 
abnormally terminate, the data set was 
cataloged. In this case, the only 
parameters reguired on the SYSCHK DD 
statement, as shown in Figure 158, are the 
DSNAME and DISP parameters. 



Noils! if a checkpoint is taken in a job 
that is running when V=R is specified, the 
job cannot be restarted until adequate 
nonpageable dynamic storage becomes 
available. 
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USING THE COMMUNICATION FEATQRE 



A communication environment consists of 
a central computer, remote or local* 
stations, and communication lines between 
such stations and the central computer- 
Use of the Communication Feature enables 
the COBOL programmer to create 
device-independent programs for 
communication applications. 



Communication applica 
special, user- written as 
program that controls th 
between the central comp 
stations. This message 
(MCP) also performs such 
required only in a commu 
environment as dial-up, 
contacting each remote s 
synchronization, as well 
device-dependent tasks a 
translation and insertio 
characters. 



tions require a 
sembler- language 
e flow of data 
uter and the remote 
control program 

additional tasks 
nication 
polling, (or 
tation) , and 

as such 
s character 
n of control 



The MCP c 
identify the 
operating sy 
between the 
of stations, 
tailored to 
••message" is 
remote stati 
from the cen 
station. An 
communicatio 



onsists of routines that 

communication network to the 
stem, establish line control 
computer and the various kinds 

and process messages in a way 
meet the needs of the user. A 

the data flowing either from a 
on to the central computer or 
tral computer to a remote 

MCP is required in a 
n system operating under TCAM. 



Depending on the needs of the 
installation, one or more COBOL programs 
may be required to process the contents of 
the messages. An example of a job needing 
no application program is message 
switching, an operation consisting only of 
forwarding messages unaltered (except for 
such processing as the MCP may perform) to 
one or more other stations. 

The MCP itself can perform limited 
processing (for example, examination of the 
first portion of a message to determine 
certain routine information and message 
code translation). Further, the MCP can 



*A station whose control unit is connected 
directly to a computer data channel by a 
local cable. 



obtain the time of day a message is 
received from a station and transmit this 
information to a COBOL program. It can 
also check the input messages to determine 
whether an error message should be sent to 
the designated station. 

This section describes the flow of a 
single-segment message through a system 
operating under TCAM, from the time it is 
entered at the remote station to its 
transmission to a destination station. 
Figure 159 outlines the flow of a message 
segment through a TCAM system. The 
encircled numerals in the flow diagram 
correspond to the steps listed in the 
description that follows. 

Because of the possible variety of both 
message types and destinations, it is often 
helpful for the user to precede the message 
"text" with a message "header" so that the 
user can transmit to the HCP information 
essential to handling the text. It is the 
user who determines which part of the 
message is the header and which part is the 
text. 

Steps 1 an d 2 ; The input message is 
prepared at the remote station and entered 
on the line. The message may be keyed in, 
or it may be entered from a card or tape 
reader. The originating station enters the 
message via a communication line, the 
transmission control unit, and the 
multiplexor channel. 

Step 3 : The message enters the central 
computer and is stored, together with the 
internally generated buffer prefix, in a 
main storage buffer. As message data fills 
the buffer, TCAM inserts the necessary 
control information in the prefix. Before 
the message characters are placed in the 
first buffer, TCAM may reserve space in the 
buffer for later insertion of the time, 
date, and sequence number for the message, 
and for control characters, if appropriate. 
Once a buffer is filled with the first 
segment of the message, the MCP controls 
the flow of the buffer through the 
communication network. The heart of the 
MCP consists of the message handlers (MH) 
constructed by the user to process messages 
from the various lines or line groups. 
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© 




© 



COBOL 

application 

program 



MCP 



Primary and Secondary Storage 



Destination queue 
for application 
program 



© 



MCP 
buffer 




03) 



(7> 



Destination queue 
for accepting station 



(14) 



MCP 
buffer 



Message Handler 



© 



Incoming Group 
of MH specified 
for the line 



Yes 




© 



Outgoing Group of 
MH specified for 
COBOL application 
program 



O 



Incoming Group of 
MH specified for 
COBOL application 
program 




15 



Outgoing Group 
of MH specified 
for the line 




Figure 159. Hessage Flo» between Remote Stations and a COBOL Program 
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S tep U : The incoming message is routed to 
the incoming group of the HH specified for 
the line (by the HH= operand of the DCB 
macro for the line group in which the line 
is included) . The message is passed, a 
buffer at a time, through the incoming 
group, which performs such user-selected 
functions on the message header as origin 
checking, and input sequence-number 
checking- Similarly, such functions may be 
performed for the message segment as 
translating the segment from line code to 
EBCDIC and causing an error message to be 
sent to the originating station when the 
incoming group detects any user-specified 
error in the segment. In performing its 
functions, the incoming group of the HH 
scans and processes header fields based on 
the relative order of the individual HH 
macro instructions. The incoming group 
then routes the message to the destination 
queue. 

Step 5 : After processing by the incoming 
group, the message is placed on a 
destination queue for either the COBOL 
program, for processing, or an accepting 
station. (If no message processing is 
necessary, the next action performed is 
that described in Step 13.) All messages 
requiring text processing are routed to the 
destination queue for the COBOL program 
that processes that type of message. The 
user controls this routing via the message 
header by placing the name of the 
destination queue for the COBOL program in 
a destination field of the message header 
or by HH macro instructions such as HSGTYPE 
that may be used to direct messages of a 
particular type to a particular queue. 

S teps 6m l t and 8 : The message from a 
destination queue for a COBOL proqram is 
placed in a main-storage buffer; the 
outgoing group of an HH (the HH is created 
especially for the application program and 
is assigned to it by the HH= operand of the 
PCB macro in the HCP) places it on the 
read-ahead queue, a special queue that 
allows overlap of HCP and application 
program processing of messages queued for a 
particular destination. 

Step 9 : Each time the COBOL program issues 
a RECEIVE statement, TCAH passes message 
data from the read-ahead queue to a 
user-specified work area in the COBOL 
program. As the message data is moved to 
the work area, TCAH removes the header or 
text prefix from the buffer. After 
receiving the message data, the COBOL 
program processes it as required and then 
generates a response message, if any is to 
be returned to a station. The destination 
queues act as buffers between the COBOL TP 
program and the remote stations. Thus, the 
COBOL communication program can accept 
messages from HCP destination queues and 



place these messages in HCP destination 
queues as if the queues were sequential 
files within a conventional COBOL program. 
(The sample COBOL program TESTTPl, shown in 
Figure 165, reads a sequential file and 
then sends each record to a destination 
queue, creating a TCAH data set for the 
COBOL communication program TESTTP2, shown 
in Figure 169, making it possible to test a 
COBOL TP program without terminals.) 



S_teps_10 and 11: When the COBOL program 
issues a SEND statement, TCAH moves the 
data from the work area into an HCP buffer 
before it is handled by the incoming group 
of the HH designed for the COBOL program. 
A header or text buffer prefix is created 
when data is moved to the buffer, as for 
other incoming messages. As the message 
data fills the buffer, TCAH inserts control 
information in the prefix field. The 
response message generated by an 
application program can be any 
user-selected length. After the buffer is 
filled, the message is handled by the 
incoming group of the HH assigned to the 
application program by the HH= operand of 
the PCB macro instruction that provides an 
interface between the HCP and the COBOL 
program. 



Ste p 12: If further processing of the 
message is required in another application 
program, the message is queued for that 
destination (and Steps 5 through 11 are 
repeated). If however, no other 
application program processing is needed, 
the processed message is placed on the 
destination queue for an accepting station. 
The destination is that specified by the 
COBOL programmer in the file referenced by 
the SYHBOLIC DESTINATION clause of the 
output CD. It may be for an application 
program or a station. 

Step., 13: The destination queue for an 
accepting station, like the destination 
queue for an application program, is a part 
of the message queues data set. TCAH 
obtains message segments from the 
destination queue on a first-ended 
first-out (FEFO) basis within priority 
groups. 

Steps 14 and 15: The message segment is 
placed in a buffer, and the outgoing group 
of the HH specified for the line processes 
the message. The HH performs such 
user-selected functions as converting the 
code of the message to the transmission 
code for the station (if necessary) , 
inserting the time and data in the header, 
logging messages, and updating message 
counts. These operations are performed in 
the buffers that receive the message 
segments from the destination queue* 
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Step 1 6: TCAM transaits the message, minus 
the header and text prefixes, to the 
appropriate station, 



WRITING A MESSAGE CONTROL PROGRAM 



The COBOL programmer can write a message 
control program (MCP) designed specifically 
for his communication needs using 
telecommunications access methods (TCAM) 
macro instructions. Using a group of TCAH 
macro instructions, the user follows in 
general the coding requirements and 
restrictions of any other 
assembler-language macro instruction. 
Guidelines for writing an MCP are contained 
in the publication Q S/VS T CAM Programmer's 
Guide. The user must tailor these general 
statements to meet the needs of the 
installation. 



The sample message co 
appears in Figure 160 in 
hypothetical program des 
COBOL applications. The 
will undoubtedly vary fr 
installation. Neverthel 
together with the sample 
TESTTP1 and TESTTP2 (sho 
and 169) can serve as an 
of COBOL programs and an 
teleprocessing applicati 
references to LOG are sh 
which would have to be c 
statements if that featu 



ntrol program that 
this chapter is a 
igned for specific 
needs of the user 
om installation to 
ess, the sample MCP 

COBOL programs 
wn in Figures 168 
excellent example 
MCP written for 
ons, Note that 
own as comments, 
hanged to valid 
re was required. 



If the MCP to be written must conform to 
the 1974 ANS standard, then Figure 160 must 
be modified (as explained later in this 
section) . 



• Determine the appropriate destination 
queue for a message and route the 
message to that queue 

• Queue the message in the appropriate 
destination queue 

• Place response messages generated by 
application programs on queues for 
subsequent transmission 

• Retrieve messages from destination 
queues and prepare them for 
transmission to remote stations 

» Perform message-editing functions for 
outgoing messages 

» Take periodic checkpoints of the system 

• Provide operator-to-system 
communications through system control 
terminals 

• Initiate corrective action when an 
error or unusual condition is detected 

• Cancel incoming messages containing 
errors 

• Reroute messages with erroneous control 
information to a special queue 

• Transmit error messages 

However, not all of these functions are 
required of an MCP. Many of the optional 
TCAM macros allow the user to write an MCP 
that includes functions that would 
otherwise have to be executed by the COBOL 
program. There are, nevertheless, some 
functions the MCP must always provide and 
in so doing follow certain conventions. 
These requirements are discussed under 
"User Tasks." 



FUNCTIONS OF THE MESSAGE CONTROL PROGRAM 



Depending on the requirements of the 
installation, the user can create an MCP to 
perform any of the following functions: 

• Enable and disable communication lines 

• Invite terminals to transmit messages 

• Receive messages from terminals 

• Dynamically assign buffers to incoming 
messages 

• Handle messages on the basis of 
user-specified priorities 

• Perform message-editing functions for 
incoming messages 



USER TASKS 



Guidelines for writing an MCP are 
contained in the publication OS/V S TCAM 
Pr ogr ammer* s. G i uide: The user must tailor 
these general statements to meet the 
specific needs of his installation. For 
example, a message can be transmitted from 
one terminal to another, from a terminal to 
an application program, or from one 
application program to another. Moreover, 
the message may contain any one of several 
types of data. 

Regardless of the specific requirements 
of the user, the MCP writer must always be 
concerned with four major tasks, as 
follows: 
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Defining the main storage buffers used 
by the MCP for handling, qaeueing, and 
transferring message data between 
communication lines and queueing 
devices. 



control information in message headers, 
prepare message segments for forwarding 
to their destination, and route 
messages to their proper destination) . 



• Defining the data sets referred to by 
the MCP, and providing for their 
activation and deactivation. 

• Defining the various terminal and line 
control areas used by the MCP (that is, 
the operating procedures and signals by 
which a teleprocessing system is 
controlled) . 

• Defining the message handlers .(the sets 
of routines that examine and process 



In carrying out each of these tasks, the 
user codes a variety of assembler- language 
macros in a specified order. Some of these 
macros mast be included in every MCP; 
others the user specifies according to the 
needs of his installation. Required as 
well as optional macros are illustrated in 
the sample MCP given in Figure 160. The 
encircled numerals in the discussion that 
follows refer to sections of code that are 
similarly labeled in the figure. 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

1 *** 

2 * 

3 * MESSAGE CONTROL PROGRAM 

4 * 

00000 5 MCP CSECT 

6 PRINT NOGEN 

7 * 

8 * IN THE FOLLOWING MACRO — 

9 * PROGID MAY BE OMITTED—IF USED, IT IS PLACED AT THE 

10 * BEGINNING OF THE EXECUTABLE CODE IN THE MCP 

11 * DISK=YES IS THE ASSUMED OPERAND — IF NO MESSAGE QUEUES DATA 

12 * SETS ARE ON DISK, CODE DISK=NO 

13 * CPB= USED IN READING FROM AND WRITING TO DISK—NEEDED IF 
II* * DISK=YES — NO. DEPENDS ON NO. OF LINES, AMOUNT OF MESSAGE 

15 * TRAFFIC AND SIZE OF BUFFER UNITS 

16 * CIB=NO. OF COMMAND INPUT BLOCKS — BUFFER-LIKE AREAS USED TO 

17 * CONTAIN OPERATOR CONTROL MESSAGES FROM SYSTEM CONSOLE — 

18 * FREED ONCE A MESSAGE PROCESSED— 2 ASSUMED AND MAX. IS 255 

19 * PRIMARY=SYSCON — THIS IS ASSUMED AND SPECIFIES THE SYSTEM 

20 * CONSOLE AS THE PRIMARY OPERATOR CONTROL TERMINAL FOR 

21 * ENTERING AND ACCEPTING OPERATOR CONTROL MESSAGES — IF A 

22 * TERMINAL IS SPECIFIED, IT MUST BE ON A NON-SWITCHED LINE 

23 * AND BE ABLE TO ACCEPT AND ENTER MESSAGES 

24 * CONTROL= — USED TO IDENTIFY OPERATOR CONTROL MESSAGES TO SYSTEM 

25 * WHEN RECEIVED FROM OTHER THAN SYSTEM CONSOLE — IS DEFAULT 

26 * AND IS VALID ONLY IF ALL OPERATOR COMMANDS ARE TO BE 

27 * ENTERED FROM SYSTEM CONSOLE 

28 * KEYLEN= — SIZE OF BUFFER UNIT — BETWEEN 33 AND 255 — 

29 * CAN ALSO SPECIFY BY UNITS Z= RATHER THAN KEYLEN= 

30 * LNUNITS= — NO. OF BUFFER UNITS TO BE USED IN BUILDING BUFFERS 

31 * FOR INCOMING AND OUTGOING MESSAGE SEGMENTS — IF TOO FEW ARE 

32 * SPECIFIED, INCOMING MESSAGE DATA MAY BE LOST — TOO MANY 

33 * WASTES STORAGE SPACE 

34 * MSUNITS= — NEEDED IF HAVE MAIN STORAGE MESSAGE QUEUES DATA SET 

35 * — NO. OF BUFFER UNITS ASSIGNED TO THIS DATA SET—IF NO DISK 

36 * BACK-UP IS SPECIFIED, MESSAGE SEGMENTS MAY' BE LOST IF NOT 

37 * ENOUGH UNITS 

38 * MSMAX= — PERCENTAGE OF UNITS IN MAIN STORAGE MESSAGE QUEUES 

39 * DATA SET WANT USED BEFORE BIT IN ERROR RECORD SET— 

40 * 70 ASSUMED 

41 * MSMIN= — PERCENTAGE OF UNITS IN MAIN STORAGE MESSAGE QUEUES 

42 * DATA SET WANT UNUSED BEFORE BIT SET NOTIFYING NO LONGER 

43 * CROWDED — MUST BE LESS THAN MSMAX — 

44 * 50 ASSUMED 

45 * (NOTE — THIS BIT ALWAYS SET IF SPECIFIED PERCENTAGE OF UNITS 

46 * UNUSED) 

47 * DLQ= — OPTIONAL — USED TO SPECIFY A TERMINAL TO RECEIVE MESSAGES 

48 * HAVING INVALID DESTINATIONS AS DETERMINED BY FORWARD MACRO 

49 * INTVAL=— AN OPERATOR CONTROL MESSAGE TELLS TCAM TO ENTER THIS 

50 * DELAY TO MINIMIZE UNPRODUCTIVE POLLING — WHEN ALL MULTIPOINT 

51 * LINES ARE INACTIVE, THE INTERVAL COMMENCES— LINES TO 

52 * SWITCHED STATIONS AND NONSWITCHED CONTENTION LINES LEFT 

53 * ACTIVE — THE OPERATOR COMMAND IS A MODIFY COMMAND REFERRED 

54 * TO AS 'INTERVAL" — THE NO. SPECIFIES THE NO. OF SECONDS 

55 * STARTUP=-IF THIS OPERAND IS OMITTED, THE USER WILL BE GIVEN 



Figure 160. A Message Control Prograa for Communication Application (Part 1 of 20) 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19.28 06/07/74 
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000512 12FF 
000514 4780 D520 



000532 9110 D718 
000536 47E0 D510 



000546 9110 D744 
00054A 47E0 D510 



00528 



00720 
00518 



0074C 
00518 
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56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 



313 
314 
315 
316 
317 
325 
326 
327 
328 
334 
335 
336 
337 
338 
344 
345 
346 
347 
348 
349 
350 
351 
352 
353 
354 
355 
363 
364 
365 



* THE OPPORTUNITY TO SPECIFY IT AT INITIALIZATION TIME AND 

* HE MAY ALSO CHANGE OTHER INTRO OPERANDS— CY MEANS ALWAYS 

* A COLD START—W SPECIFIES A WARM START AFTER A QUICK OR 

* FLUSH CLOSEDOWN AND A CONTINUATION AFTER A SYSTEM FAILURE 

* — W INDICATES THE CONTINUATION RESTART WILL INCLUDE FULL 

* SCANNING OF THE QUEUES — WY IS THE SAME AS W EXCEPT NO 

* SCANNING OF THE QUEUES FOR ALREADY SENT MESSAGES IS DONE-- 

* --A CHECKPOINT DATA SET IS NEEDED FOR ANYTHING BUT A COLD 

* START—ALSO, IF DD CARD FOR CHECKPOINT DATA SET SPECIFIES 

* DISP=NEW, WILL GET A COLD START REGARDLESS 

* OLTEST=IF DO NOT WISH ON-LINE TEST FACILITY — CODE 

* FEATURE= THE DEFAULTS ARE DIAL, 2741, AND TIMER — SINCE WE DO 

* NOT HAVE A 2741 TERMINAL, WE ARE CODING TO INDICATE THIS 

* LINETYP= STSP SPECIFIES START-STOP LINES ONLY, BISC SPECIFIES 

* BSC LINES ONLY, MINI SPECIFIES ALL TERMINALS ARE IBM 1050 

* ON LEASED LINES, BOTH IS DEFAULT AND INDICATES ALL TYPES 

* OF LINES ARE SUPPORTED — IF THE LINES IN THE SYSTEM DO NOT 

* FALL UNDER THE 'BOTH' CATEGORY, SPACE IS SAVED BY CODING 

* THIS OPERAND 

* DTRACE — PUT IN FOR TESTING ONLY TEST * 
* 

INTRO PROGID=MCP,DISK=YES,CPB=10,CIB=2,PRIMARY=SYSCON, X 

CONTROL=TCAM , KEYLEN=1 00 , LNUNITS= 2 , MSUNITS= 50 , MSMAX=7 5 , X 
MSMIN=50, DLQ=T1, INTVAL=1200, STARTUP=W, OLTEST=0, X 

FEATURE= (DIAL, N02741, TIMER) ,LINETYP=BOTH, X 

DTRACE=700 
* 

* TEST IF INTRO MACRO WORKED SUCCESSFULLY 

LTR 15,15 

BZ OPENFILE YES 

ABEND ABEND 12 3, DUMP INTRO OR AN OPEN FAILED 

* THE MESSAGE QUEUES DATA SET MUST BE OPENED FIRST IF IT RESIDES ON 

* DISK — A MAIN STORAGE MESSAGEOUEUES DATA SET IS NOT OPENED 
OPENFILE OPEN (MSGQ, (INOUT) ) (a) 

TM MSGQ+48,X , 10* ^^ CHECK IF OPEN SUCCESSFUL 
BNO ABEND BRANCH IF NOT 

* 

* IF THE CHECKPOINT DATA SET IS USED, IT MUST BE OPENED NEXT 

OPEN (CHKPT, (INOUT)) (b) 

TM CHKPT+48.X , 10' CHECK IF OPEN SUCCESSFUL 
BNO ABEND BRANCH IF NOT 

* 

* OPEN LINE GROUP DATA SETS — LINES WILL BE ACTIVATED SINCE IDLE NOT 

* SPECIFIED 

* NOTE — WE ARE NOT CHECKING FOR OPEN ERRORS FOR THE LINES — SINCE THERE 

* IS PROBABLY NO NEED TO STOP THE SYSTEM IF SOME OF THE LINES ARE NOT 

* WORKING—MESSAGES WILL BE PRINTED ON THE SYSTEM CONSOLE FOR LINES 

* THAT ARE NOT WORKING — 

* IF A LINE BECOMES OPERATIONAL DURING A RUN, IT CAN THEN BE STARTED 

* BY THE VARY COMMAND USED TO START A LINE WHICH IS OPENED AS IDLE 

OPEN (LN1050, (INOUT),LNTWX» (INOUT) ) (c) 



* OPEN LOG DATA SET (d) 



NEXT IWD DISABLED- 



Figure 160. h Message Control Program for Communication Applications (Part 2 of 20) 
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LOC OBJECT CODE 



00056A 9110 D834 
00056E 47E0 D510 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19.28 06/07/74 



0083C 
00518 



0005EE 58DD 0004 



00004 
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© 



366 
367 
368 
369 
370 
376 
377 
378 
379 
380 
397 
398 
410 
411 
412 
420 
421 
427 
428 
429 
430 
431 
437 
438 
439 
445 
446 
447 
448 
449 
450 
454 



OPEN ( MSGLOG, (OUTPUT ) ) 

TM MSGLOG+48.X*10* CHECK IF OPEN SUCCESSFUL 

BNO ABEND BRANCH IF NOT 

TEST*** 

OPEN (DUMP. (OUTPUT) ) (e) FOR SNAPS 

TM DUMP+48,X'10* CHECK IF OPEN SUCCESSFUL 

BNO ABEND BRANCH IF NOT 

ISSUE THE FOLLOWING BETWEEN THE OPENING AND CLOSING OF THE DATA SETS 
READY 

TEST*** 
SNAP DCB=DUMP, PDATA=ALL * 

CLOSE DATA SETS 

CLOSE (LN1050,,LNTWX)(a) LINE GROUP DATA SETS 



CLOSE (DUMP.DISP) (b) SNAP DATA SET 

CLOSE (MSGLOG. DISP) (c) LOG DATA SET 

ALWAYS CLOSE CHECKPOINT DATA SET NEXT TO LAST 
CLOSE (CHKPT,DISP)@ 

THE MESSAGE QUEUES DATA SET MUST ALWAYS BE CLOSED LAST 
CLOSE (MSGQ.DISP) (e) 



NEXT IWD DISABLED--* 



RETURN TO OS SUPERVISOR 
L 13.4(13) 



PICK UP ADDRESS OF SYSTEM SAVE AREA SAVED 
IN IEDSAVE1 — ADDRESS OF IEDSAVE1 WAS PUT 
IN REG. 13 WHICH WAS MADE BASE REGISTER 



RETURN (14.12),RC=0 



Figure 160. A Message Control Program for Coaaunication Applications (Part 3 of 20) 
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PAGE 6 

LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19-28 06/07/74 

456 **** 
K57 * 

458 * DATA DEFINITIONS — PROCESS CONTROL BLOCKS AND DATA CONTROL BLOCKS 

459 * 

460 **** 

461 * 

462 * PCB — PROCESS CONTROL BLOCK — USED TO COMMUNICATE BETWEEN THE MCP 

463 * AND AN APPLICATION PROGRAM — 

464 * ONE PCB IS NEEDED FOR EACH ACTIVE APPLICATION PROGRAM 

465 * 

466 * IN THE FOLLOWING MACRO— 

467 * MH= GIVES THE SYMBOLIC ADDRESS OF THE MESSAGE HANDLER FOR THIS 

468 * APPLICATION PROGRAM 

469 * BUFSIZE= SPECIFIES SIZE OF BUFFERS TO HANDLE MESSAGES FOR 

470 * APPLICATION PROGRAM 

471 * BUFIN= INITIAL NO. OF BUFFERS INTO WHICH USERS WRITE WORK AREA 

472 * EMPTIED — OPTIMUM NO. IS ENOUGH FOR ALL OF WORK AREA — BETWEEN 

473 * 2 AND 15 — 2 ASSUMED 

474 * BUFOUT= INITIAL NO- OF BUFFERS THAT MAY BE FILLED IN ANTICIPATION 

475 * OF A READ — BETWEEN 2 AND 15 — 2 ASSUMED 

476 * RESERVE=NO. OF BYTES TO RESERVE FOR INSERTION OF CHARS. BY DATETIME 

477 * AND SEQUENCE MACROS FOR MESSAGES COMING FROM APPLICATION PROGRAMS 

478 * DATE=YES — THIS IS NEEDED FOR ALL PCB ENTRIES FOR A COBOL PROGRAM. 

479 * THIS WILL MAKE THE DATE AND TIME AVAILABLE SO IT MAY BE PLACED 

480 * IN THE COBOL PROGRAM INPUT CD— (IT IS ALSO NEEDED ON AN INPUT 

481 * TPROCESS ENTRY) 

482 * 

483 * PROCESS CONTROL BLOCK FOR COBOL PROGRAM RUNNING WITH TERMINALS 

484 * Q 

485 PCBLK PCB v - y MH=MHTRMAPP,BUFSIZE=100, BUFIN=2,BUFOUT=5,RESERVE=21 f X 
DATE=YES 

518 * 

519 * PROCESS CONTROL BLOCK FOR COBOL PROGRAMS THAT SIMULATE TERMINAL 

520 * INPUT DATA — USED FOR TESTING WITHOUT TERMINALS 

521 * (b) 

522 PCBLK1 PCBV-' MH=MHAPPAPP„ BUFSIZE=100,BUFIN=2,BUFOUT=5,DATE=YES 

555 * 

556 * PROCESS CONTROL BLOCK FOR COBOL PROGRAMS TESTING MESSAGES SENT TO 

557 * DESTINATIONS DEFINED BY A QUEUE STRUCTURE 

558 * 

559 * IT USES THE SAME MH THAT PCKBLK1 USES 

561 PCBLK2 PCB^' MH=MHAPPAPP,BUFSIZE=100,BUFIN=2,BUFOUT=5,DATE=YES 

594 * 

595 * DCBS 

596 ♦ 

597 * DCB FOR MESSAGE QUEUES DATA SET 

598 * IN THE FOLLOWING MACRO — 

599 * OPTCD=R SPECIFIES REUSABLE DISK — IF NON-REUSABLE, SPECIFY L 

600 * THRESH= SHOULD PROBABLY BE USED IF NON- REUSABLE DISK-- 

601 * SPECIFIES PERCENTAGE OF RECORDS TO BE USED BEFORE A FLUSH 

602 * CLOSEDOWN INITIATED — A CERTAIN PERCENTAGE ASSUMED 

603 MSGQ DCB,r>. DSORG=TQ t ,MACRF=(G.P),DDNAME=QFILE,OPTCD=R 

637 * <jy 

638 * DCB FOR THE CHECKPOINT DATA SET 
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Figure 160. A Message Control Program for Communication Applications (Part 4 of 20) 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19.28 06/07/74 



639 
673 
674 
675 
676 
677 
678 
679 
680 
681 
682 
683 
684 
685 
686 
687 
688 
689 
690 
691 
692 
693 
694 
695 
696 
697 
698 
699 
700 
701 
702 
703 
704 
705 
706 
707 
708 
709 
710 
711 
712 



749 
750 
751 
752 
753 



790 
791 
792 
793 
794 



DCE 



DSORG=TQ # MACRF= (G, P) , DDNAME=CFILE« OPTCD=C 



DCB FOR THE 1050 LINE GROUP 
IN THE FOLLOWING MACRO— 

CPRI=R INDICATES THAT RECEIVE HAS PRIORITY OVER SENDING-- 

S INDICATES THAT SENDING HAS PRIORITY OVER RECEIVING — 
E INDICATES EQUAL PRIORITY — 
FOR SWITCHED LINES, S MUST BE SPECIFIED 

BUFIN=NO. OF BUFFERS TO ASSIGN INITIALLY FOR RECEIVING FOR 
EACH LINE — 1 ASSUMED — 15 MAXIMUM 

BUFOUT=NO. OF BUFFERS TO ASSIGN INITIALLY FOR SENDING FOR 
EACH LINE — 2 ASSUMED — 15 MAXIMUM 

BUFMAX=MAX. NO. OF BUFFERS TO BE USED FOR DATA TRANSFER FOR 
EACH LINE IN LINE GROUP — NO LESS THAN LARGER OF BUFIN AND 
BUFOUT — 15 MAXIMUM 

BUFSIZE=BUFFER SIZE IN BYTES USED FOR ALL LINES IN THIS LINE 
GROUP — SIZE SHOULD BE A MULTIPLE OF THE BUFFER UNIT SIZE 
SPECIFIED IN KEYLEN= OPERAND OF INTRO MACRO— (MAY BE 
OVERRIDDEN ON A STATION BASIS BY BUFSIZE= OPERAND OF THE 
TERMINAL MACRO) 

INVLIST=NAMES OF INVITATION LISTS FOR LINES OF LINE GROUP 
—INVITATION LIST NAMES ARE SPECIFIED ACCORDING TO THE 
ASCENDING RELATIVE LINE NOS. OF THE LINES IN THE GROUP 

MH=ADDRESS OF MESSAGE HANDLER 

PCI=SPECIFIES IF AND HOW A PROGRAM- CONTROLLED INTERRUPTION 
TO BE USED FOR BUFFER ALLOCATION AND DEAELOCATION — 1ST 
SUBOPERAND REFERS TO RECEIVING AND 2ND TO SENDING — 
N SPECIFIES NO PCIS— R SPECIFIES AFTER 1ST BUFFER, COMPLETED 
BUFFER DEALLOCATED — A IS ASSUMED AND SPECIFIES AFTER 1ST 
BUFFER, COMPLETED BUFFER DEALLOCATED AND ANOTHER BUFFER IS 
ALLOCATED 

RESERVE=NO. OF BYTES TO RESERVE FOR INSERTION OF CHARS. BY 
DATETIME AND SEQUENCE MACROS 

TRANS=TRANSLATION TABLE 

SCT=SPECIAL CHARACTERS TABLE v 

(IF CPRI=R AND NON-SWITCHED LINE, NEED INTVL= OR NO MESSAGES 

ARE SENT— INTVL=NO. OF SECONDS TO DELAY AFTER PASS THRU 

INVITATION LIST — NO LARGER THAN 255 — TOO SHORT A DELAY CAUSES 

MESSAGES TO ACCUMULATE) 

M.050 DCbC£/ DSORG=TX,MACRF=(G,P),CPRI=S,DDNAME=LNl,BUFIN=2, J 

BUFOUT=4,BUFMAX=4,BUFSIZE=100,INVLIST=(LIST1050), > 
MH=MH1050, PCI= (A, A) . RESERVE=21, TRANS=105F, SCT=105F 

DCB FOR THE TWX LINE — SEE DESCRIPTION OF OPERANDS BEFORE DCB FOR 
1050— LN1050 

STWX DCB^-' DSORG=TX«MACRF=<G,P>,CPRI=S,DDNAME=LN2,BUFIN=2, > 

BUFOUT=4„ BUFMAX=4« BUFSIZE=100, INVLIST= (LISTTWX) , X 
MH=MHTWX, PCI= (A, A) , RESERVE=21 ,TRANS=TTYC, SCT=TTYC 

DCB' FOR LOG DATA SET 

IN THE FOLLOWING MACRO— * 

BLKSIZE= — THE VALUE SHOULD BE THE SAME AS IN KEYLEN OPERAND OF 

INTRO MACRO * 



LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19.28 06/07/74 



NCP= — MAX. NO. OF BUFFER UNITS THAT MAY APPEAR IN A BUFFER 
B©> 



795 * 

796 * 

797 MSGLOG DCBV5^ DSORG=PS.MACRF=(W) ,DDNAME=LOGFILE,BLKSIZE=100.RECFM=F, *X 

^ NCP=2 » 

848 * (f) TEST*** 

849 * DCB FOR SNAPS * 

850 DUMP DCB DSORG=PS.RECFM=VBA,MACRF=(W) ,LRECL=125,DDNAME=LRDUMP, *X 

BLKSIZE=882 * 



Figure 160. A Message Control Prograa for Communication Applications (Part 5 of 20) 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

902 **** 

903 * 

904 * TERMINAL AND LINE CONTROL—DEFINES TERMINAL TABLE ENTRIES AND THE 

905 * INVITATION LISTS FOR EACH LINE 

906 * 

907 **** 

908 * 

909 * DEFINE THE TERMINAL TABLE 

910 * LAST= NAME OF LAST ENTRY IN TABLE 

911 * MAXLEN= NUMBER OF CHARACTERS IN LONGEST NAME 

912 * 

913 TTABLE LAST=D1«MAXLEN=5 

942 * NOTE* 

943 * IF ANY OPTION MACROS ARE NEEDED, THEY GO HERE—DATA GOES IN ENTRIES * 

944 * USING THE OPDATA= OPERAND OF THE TERMINAL OR TPROCESS ENTRIES 

945 * 

946 * ENTRY FOR 1050 TERMINAL 

947 * IN THE FOLLOWING MACRO — 

948 * QBY= T SPECIFIES THAT OUTGOING MESSAGES ARE TO BE QUEUED BY 

949 * TERMINAL — USE L IF BY LINE 

950 * — MUST QUEUE BY TERMINAL IF A SWITCHED STATION OR A 

951 * BUFFERED TERMINAL 

952 * DCB= DCBNAME FOR LINE 

953 * RLN=RELATIVE LINE NO. WITHIN THE LINE GROUP OF THIS LINE 

954 * TERM=SPECIFIES TYPE OF TERMINAL 

955 * QUEUES=MR SPECIFIES MESSAGE QUEUES KEPT IN MAIN STORAGE WITH 

956 * BACKUP ON REUSABLE DISK 

957 * ADDR=6213 IS A9 IN 1050 CODE — USED WHEN COMPUTER HAS MESSAGE 

958 * TO SEND— 9 IS CODE FOR ANY OUTPUT DEVICE 

959 * ALTDEST=IS NEEDED BECAUSE THIS IS REUSABLE DISK — NEEDED SO 

960 * MESSAGE IS NOT DISCARDED AT ZONE CHANGEOVER 

961 * NTBLKSZ= THE NO. OF CHARS. BETWEEN INSERTION OF EOB CHARS. 

962 * IN OUTPUT MSG. WHEN MSGFORM CODED IN OUTHDR 

963 * (S) 
S-'n 
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964 Tl TERMINAL V "'QBY=T,DCB=LN1050,RLN=1,TERM=1050,QUEUES=MR, 
ADDR= 6213, ALTDEST=T 1 , NTBLKS Z= ( 1 2 ) 

994 * 

995 * DEFINE ENTRY FOR THE SWITCHED TWX LINE WHICH CAN BE USED BEFORE AN 

996 * ORIGIN MACRO IS ISSUED TO IDENTIFY THE STATION 

997 * UTERM=YES IDENTIFIES THIS AS SUCH AN ENTRY 

998 * THIS MACRO MUST PRECEDE ALL TERMINAL MACROS FOR STATIONS ON LINE 

999 * IN THE FOLLOWING MACRO — 

1000 * ALWAYS SPECIFY DCB NAME. RELATIVE LINE NO., TERMINAL TYPE, 

1001 * AND QUEUES 

1002 * — ADDR= MIGHT BE CODED IF STATION HAD ADDRESSING CHARS. — IF 

1003 * USED, ALL STATIONS ON LINE MUST HAVE IDENTICAL ADDRESSING 

1004 * CHARACTERS 

1005 * (b) 

1006 T2A TERMINAL UTERM= YES, DCB=LNTWX,RLN=1,TERM=33 35, QUEUES=MR 

1030 * 

1031 * TERMINAL ENTRY FOR TWX TERMINAL — SEE DESCRIPTION OF MOST OF OPERANDS 

1032 ♦ PRECEDING TERMINAL MACRO FOR 1050 

1033 * IN ADDITION — 

1034 * DIALNO= SPECIFIES TELEPHONE NO. OF STATION AND MUST BE 

1035 * SPECIFIED FOR SWITCHED STATIONS — CODE 'NONE* IF NO AUTO 



Figure 160. A Message Control Program for Communication Applications (Part 6 of 20) 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

1036 * CALL FEATURE 

1037 + ADDR= IS NOT GIVEN SINCE THIS STATION IS ON A SWITCHED LINE 

1038 * NTBLKSZ IS NOT USED FOR TWX TERMINALS 

1039 * CINTVL= NO. OF SECONDS BEFORE COMPUTER SHOULD CALL STATION 

1040 * — NOT NEEDED IF NO AUTO CALL FEATURE 

1041 * (c) 

1042 T2 TERMINAL V - / QBY=T.DCB=LNTWX,RLN=1,TERM=3335,QUEUES=MR. X 

DI ALNO=NONE , ALTDEST=T2 

1063 * 

1064 * TPROCESS ENTRIES 

1065 * 

1066 * IN THE FOLLOWING MACROS — 

1067 * PCB= NAME OF PROCESS CONTROL BLOCK — ALL TPROCESS 

1068 * ENTRIES FOR THE SAME APPLICATION PROGRAM MUST HAVE THE SAME 

1069 * PCB 

1070 * QUEUES= IS THE SAME AS FOR A TERMINAL MACRO — HOWEVER, BY 

1071 * OMITTING, USER SPECIFIES THAT THIS ENTRY IS USED FOR PUTS 6 

1072 * WRITES FROM APPLICATION PROGRAM 

1073 * ALTDEST= FOR OUTPUT, GIVES WHERE REPLIES TO OPERATOR MSGS. SENT 

1074 * IF WERE ENTERED FROM AN APPLICATION PROGRAM — NOT APPLICABLE 

1075 * TO COBOL — 

1076 * ONLY NEEDED FOR INPUT QUEUES IF REUSABLE DISK QUEUEING 

1077 * RECDEL= SPECIFIES CHARACTER USED TO DENOTE END OF RECORD 

1078 * DATE=YES — THIS IS NEEDED FOR ALL INPUT TPROCESS ENTRIES 

1079 * FOR A COBOL PROGRAM. THIS WILL MAKE THE DATE AND TIME 

1080 * AVAILABLE SO IT MAY BE PLACED IN THE COBOL PROGRAM 

1081 * INPUT CD. 

1082 * 

1083 * INPUT TPROCESS ENTRY FOR COBOL PROGRAM RUNNING WITH TERMINALS 

1084 * 

1085 PIN TPROCESS PCB=PCBLK,QUEUES=MR,ALTDEST=PIN,RECDEL=FF„DATE=YES (a) 

1114 * 

1115 * OUTPUT TPROCESS ENTRY FOR COBOL PROGRAM RUNNING WITH TERMINALS 

1116 * 

1117 POUT TPROCESS PCB=PCBLK # RECDEL=FF (b) 

1141 * 

1142 * THE FOLLOWING TWO INPUT TPROCESS ENTRIES ARE FOR COBOL PROGRAMS 

1143 * THAT SIMULATE TERMINAL INPUT DATA — USED FOR TESTING WITHOUT 

1144 * TERMINALS 

1145 * 

1146 PI TPROCESS PCB=PCBLK1,QUEUES=MR,ALTDEST=P1,RECDEL=FF„DATE=YES (c) 

1170 * 

1171 P2 TPROCESS PCB=PCBLK1,QUEUES=MR.ALTDEST=P2,RECDEL=FF„DATE=YES (d) 

1195 * 

1196 * OUTPUT TPROCESS ENTRY FOR THESE COBOL PROGRAMS 

1197 * 

1198 POUT1 TPROCESS PCB=PCBLK1,RECDEL=FF (e) 

1222 * 

1223 * THE FOLLOWING SIX INPUT TPROCESS ENTRIES ARE FOR COBOL QUEUE 

1224 * STRUCTURE TEST PROGRAMS 

1225 * 

1226 PQ1 TPROCESS PCB=PCBLK2,QUEUES=MR,ALTDEST=PQ1,RECDEL=FF«DATE=YES 

1250 * 

1251 PQ2 TPROCESS PCB=PCBLK2, QUEUES=MR„ ALTDEST=PQ2,RECDEL=FF, DATE=YES 
1275 * 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19-28 06/07/74 



® 



® 



1276 
1300 
1301 
1325 
1326 
1350 
1351 
1375 
1376 
1377 
1378 
1402 
1403 
1404 
1405 
1406 
1407 
1408 
1409 
1410 
1411 
1412 
1413 
1414 
1415 
1416 
1417 
1418 
1419 
1420 
1421 
1422 
1423 
1451 
1452 
1453 
1454 
1455 
1456 
1457 
1458 
1459 
1460 
1461 
1462 
1463 
1464 
1465 
1466 
1477 
1478 
1479 
1480 
1481 
1482 



PQ3 TPROCESS PCB=PCBLK2,QUEUES=MR.ALTDEST=PQ3,RECDEL=FF.DATE=YES 

PQ4 TPROCESS PCB=PCBLK2«QUEUES=MR.ALTDEST=PQ4,RECDEL=FF,DATE=YES 

* 

PQ5 TPROCESS PCB=PCBLK2,QUEUES=MR.ALTDEST=PQ5,RECDEL=FF,DATE=YES 

* 

PQ6 TPROCESS PCB=PCBLK2,QUEUES=MR.ALTDEST=PQ6,RECDEL=FF, DATE=YES 

* OUTPUT TPROCESS ENTRY FOR COBOL QUEUE STRUCTURE TEST PROGRAMS 
* 

PQOUT TPROCESS PCB=PCBLK2,RECDEL=FF 

* 

* 

* DISTRIBUTION LIST ENTRY — 
* 

♦IN THE FOLLOWING MACRO — 

* LIST = NAMES OF TERMINAL OR TPROCESS ENTRIES IN THE 

* TERMINAL TABLE 
* 

* THE LIST SHOULD NOT INCLUDE A TPROCESS ENTRY FOR A 

* .COBOL APPLICATION PROGRAM 
* 

* TYPE= D SPECIFIES THIS IS A DISTRIBUTION LIST ENTRY 

* C WOULD SPECIFY A CASCADE LIST ENTRY 

* DISTRIBUTION LISTS INDICATE A MESSAGE FORWARDED TO THEM 

* WILL BE SENT TO ALL NAMES IN THE LIST 
* 

* WITH CASCADE LISTS, MESSAGES WILL BE SENT TO THE QUEUE 

* SPECIFIED IN THE LIST WITH THE FEWEST NO- OF MESSAGES 
* 

* 1050 AND TWX — USED BY MESSAGE PROCESSING PROGRAM 

* 

Dl TLIST LIST=(T1.T2)«TYPE=D (a) 
* 

* INVITATION LISTS 

* SHOULD ALWAYS BE SPECIFIED FOLLOWING THE MACROS DEFINING THE TERMINAL 

* TABLE 
* 

* LIST FOR 1050 LINE — 

* ORDER= ENTRIES FOR STATIONS ON LINE IN THE ORDER TO BE POLLED 

* Tl SPECIFIES A STATION ON THE LINE DEFINED BY A TERMINAL 

* MACRO 

* + SPECIFIES THE TERMINAL IS INITIALLY ACTIVE. - WOULD 

* SPECIFY IT WAS INITIALLY INACTIVE 

* 6215=A0 IN 1050 CODE — A IS THE STATION ADDRESS — ASKS FOR 

* INPUT FROM ANY INPUT COMPONENT 



LIST1050 INVLIST ORDER=(Tl+6215) 



* LIST FOR TWX LINE — 

* SINCE A TERMINAL MACRO WITH UTERM=YES WAS DEFINED FOR THIS LINE. 

* THIS MACRO NAME IS USED RATHER THAN THE ONE FOR THE TWX STATION 

* THIS IS A SWITCHED LINE WHICH DOES NOT HAVE THE AUTO-CALL FEATURE— 



LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19-28 06/07/74 



000864 0C 

000865 01B151FFC3F343F3 



1483 
1484 
1485 
1486 
1487 
1488 
1489 
1490 
1491 
1492 
1493 
1494 
1495 
1496 
1497 
1508 
1509 
1510 
1511 
1512 
1513 
1514 



* THE COMPUTER NEVER ASKS FOR THE ID SEQUENCE FROM THE TWX TERMINAL 

* UNLESS THE AUTO-CALL FEATURE IS PRESENT 
* 

* IF AUTO-CALL FEATURE IS NOT PRESENT OR TWX TERMINAL DOES NOT HAVE 

* AN ID SEQUENCE FOR AN ANSWER-BACK, OMIT THE ID SEQUENCE CHARS- IN 

* THE INVLIST MACRO 
* 

* IF AN ID SEQUENCE IS USED FOR THE TWX — IT IS SUGGESTED THE 

* FOLLOWING CHARACTERS BE USED — CR LF IDCHARS CR LF XON — IN LINE 

* CODE 
* 

* THE CPUID OPERAND IS NEEDED FOR TWX TERMINALS — IT WILL PRINT AT 

* TERMINAL WHEN CONNECTION IS MADE 
* 

LISTTWX INVLIST ORDER=(T2A+>,CPUID=TWXSEQ (b) 

* REFERENCED BY LISTTWX AS CPUID OPERAND 

* — SUGGESTED USE NULL CR LF RUBOUT IDCHARS CR LF XON 

* CPUID IS — COBOL 

TWXSEQ DC X'OC 12 CHARACTERS 

DC X' 01B151FFC3F343F333B15189" 
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LOC OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

1516 **** 

1517 * 

1518 * MESSAGE HANDLERS — MH'S 

1519 * 

1520 * THE HEADER RECEIVED FROM THE TERMINAL IS — 

1521 * POSSIBLE LINE FORMAT CHARS. — CR,LF,NL 

1522 * $ 

1523 * BLANK 

152<» * MSGTYPE — 1 CHAR. 

1525 * BLANK 

1526 * SOURCE--2 CHARS. 

1527 * BLANK 

1528 * EOF FIELD — F IF END OF A GROUP OF MESSAGES 

1529 * —ANY OTHER CHAR. (EXCEPT BLANK) IF NOT 

1530 * BLANK 

1531 * ACTION CODE FOR APPLICATION PROGRAM— 2 CHARS. 

1532 * BLANK 

1533 * PUNCTUATION MARK— PERIOD 
153« * 

1535 **** 

1536 *** 

1537 * MESSAGE HANDLER FOR INPUT FROM AND OUTPUT TO 1050 TERMINAL 

1538 * 

1539 * THE FOLLOWING MACRO IS REQUIRED AND MUST BE FIRST 

1540 * LC= IS THE ONLY REQUIRED OPERAND— 

1541 * OUT SAYS TO REMOVE LINE CONTROL CHARS. 

1542 * IN SAYS NOT TO REMOVE LINE CONTROL CHARS. 

1543 * STOP= SAYS WHEN EOB ERROR FOUND AND RETRY COUNT EXHAUSTED, 

1544 * ONLY THAT PORTION OF MESSAGE RECEIVED OR SENT CONTINUES 

1545 * THRU MH— USER MAY CHECK ERROR RECORD BITS IN INMSG OR OUTMSG 

1546 * CONT= SAYS THAT AFTER RETRY, SET BIT IN ERROR RECORD — BUT 

1547 * CONTINUE TRANSMISSION 

1548 * IF NEITHER STOP NOR CONT SPECIFIED, NO EOB CHECKING PERFORMED 

®1549 * 
1550 MH1050 STARTMH LC=OUT, CONT=YES 
1572 * 

1573 * THE FOLLOWING MACRO IS REQUIRED AS THE FIRST MACRO IN ANY INCOMING 

1574 * GROUP 

1575 INHDR 

1589 * 

1590 * THE FOLLOWING MACRO TRANSLATES FROM LINE CODE TO EBCDIC — MACROS 

1591 * FOLLOWING THIS WILL ACT UPON CHARACTERS IN EBCDIC — IT WILL CAUSE 

1592 * ENTIRE MESSAGE TO BE TRANSLATED EVEN THOUGH IN INHDR GROUP 

1593 CODE 

1617 * 

1618 * LOG INCOMING HEADERS — USE DCBNAME AS OPERAND 

1619 * NEXT IWD DISABLED — * 

1620 * LOG MSGLOG 

1621 * 

®1622 * SET SCAN POINTER TO $ 
1623 SETSCAN C'$' 

1639 * 

1640 * PROCESS THE REMAINDER OF THE HEADER ACCORDING TO THE MSGTYPE FIELD 

1641 * SPECIFIED NEXT IN THE HEADER— IF THE NEXT FIELD MATCHES THE CHARACTER 

1642 * SPECIFIED IN THE OPERAND, THE MACROS SPECIFIED BETWEEN IT AND THE 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

16l»3 * NEXT MSGTYPE MACRO ARE EXECUTED AND CONTROL IS THEN PASSED TO THE 

1644 + NEXT DELIMITER—IN THIS CASE INBUF -IF THEY DO NOT MATCH, CONTROL 

1645 * PASSES TO THE NEXT MSGTYPE MACRO WHERE THE TEST IS AGAIN MADE 

®1646 * 
1647 * IF MSGTYPE IS 1, THIS MESSAGE SHOULD BE FORWARDED TO THE 1050 
1648 MSGTYPE C'l' 

1664 * 

1665 * SCAN POINTER IS AT SOURCE FIELD — SINCE THIS IS A NON-SWITCHED STATION 

1666 * — ORIGIN VERIFIES THAT THE SOURCE FIELD CONTAINS THE SYMBOLIC NAME 

1667 * OF THE STATION THAT WAS INVITED TO SEND THE MESSAGE — IF NOT, ERROR 
Oi 1668 * BIT IN ERROR RECORD FOR MESSAGE IS SET TO 1 

Vjv 1669 ORIGIN 

(TO) 1682 FORWARD DEST=C*T1* 

W 1700 ♦ 

1701 * IF MSGTYPE IS 2, THIS MESSAGE SHOULD BE FORWARDED TO TWX TERMINAL — 

1702 * SEE COMMENTS UNDER MSGTYPE 1 FOR OTHER MACROS 

1703 MSGTYPE C*2* 
1721 ORIGIN 

1731 FORWARD DEST=C'T2* 

1746 * 

1747 * IF MSGTYPE IS 5, THIS MESSAGE SHOULD BE FORWARDED TO THE COBOL 

1748 * APPLICATION PROGRAM-- 

1749 * SEE COMMENTS UNDER MSGTYPE 1 FOR OTHER MACROS 

1750 MSGTYPE C" 5« 
1768 ORIGIN 

1778 FORWARD DEST=C« PIN' 

1793 * 

1794 * IF MSGTYPE IS 6, THE SOURCE FIELD HAS BEEN OMITTED — UNNECESSARY TO 

1795 * ISSUE AN ORIGIN FOR A NON-SWITCHED LINE — SEND MESSAGE TO THE COBOL 

1796 * APPLICATION PROGRAM 

1797 MSGTYPE C'6" 

1815 FORWARD DEST=C'PIN' 

1830 * 

1831 * IF THE MSGTYPE IS ANYTHING ELSE. IT IS INVALID — SET THE USER ERROR 

1832 * BIT WITH THE TERRSET MACRO— IN THE INMSG GROUP, WE WILL CANCEL MSG- — 

1833 * ISSUE FORWARD MACRO ANYWAY SINCE REQUIRED 

1834 MSGTYPE 

®1839 FORWARD DEST=C'T1' 

1854 TERRSET 

1861 * 

1862 * THE MACROS IN THE FOLLOWING SUBGROUP ARE EXECUTED FOR EVERY BUFFER 

@1863 * OF THE MESSAGE 
1864 INBUF 

1869 + 

1870 * SPECIFY THE MAXIMUM NO. OF CHARACTERS ALLOWED IN AN INCOMING MESSAGE 

1871 * — THIS MACRO ALSO CHECKS IF THE INPUT BUFFER IS FILLED WITH IDENTICAL 

1872 * CHARACTERS, USUALLY AN INDICATION OF STATION MALFUNCTION— SETS A 

@1873 * BIT IN ERROR RECORD FOR EITHER CONDITION 
1874 CUTOFF 900 

1885 * 

1886 * INSERT X'FF' FOR EVERY NL AND LF CHARACTER— X'FF' IS THE RECDEL CHAR. 

1887 * SPECIFIED IN THE TPROCESS MACROS—IF A MESSAGE WERE ALWAYS BEING 

1888 * FORWARDED TO AN APPLICATION PROGRAM, WE COULD USE DELIMIT INSTEAD 
^-^ 1889 * OF XLl'FF' 

(24) 1890 MSGEDIT ( (RA.XLl'FF" ,XL1* 15* ) , <RA,XL1« FF' ,XL1' 25' ) ) 



Figure 160. A Hessage Control Prograa for Communication Applications (Part 10 of 20) 



Using the Coaaunication Feature 415 



© 
® 



LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19-28 06/07/74 

1919 * 

1920 * THE INMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS — IT IS EXECUTED 

1921 * AFTER AN ENTIRE MESSAGE OR BLOCK HAS BEEN PROCESSED — NO EXECUTABLE 

1922 * USER-WRITTEN CODE SHOULD BE INCLUDED IN THIS SUBGROUP 

1923 INMSG 

1931 * 

1932 * CANCELMG CAUSES IMMEDIATE CANCELLATION OF MESSAGE IF ANY ERRORS 

1933 * SPECIFIED BY ITS MASK OCCUR — IF USED, IT MUST BE 1ST MACRO UNDER 

1934 * INMSG — AN ERRORMSG MACRO MAY THEN NOTIFY OF THE ERROR — 

1935 * CANCELMG IF THE USER ERROR BIT IS SET INDICATING THE MSGTYPE FIELD 

1936 * WAS INVALID--BIT20 

1937 CANCELMG X' 0000080000* 

1945 * 

1946 * IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

1947 * SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

1948 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 

1949 * THE MESSAGE INCLUDES THE HEADER OF THE MESSAGE IN ERROR AND THE 

1950 * ERROR MESSAGE 

1951 * 

1952 * THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

@1953 * RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 
1954 ERRORMSG X* 8000000000*«DEST=C'T1* , X 

DATA=C*E ERROR IN PROCESSING HEADER * 
1970 ERRORMSG X* 4000000000* ,DEST=C*T1* , X 

DATA=C'E INVALID ORIGIN IN HEADER * 
1982 ERRORMSG X* 0200000000*, DEST=C*T1* , X 

DATA=C*E INSUFFICIENT BUFFERS FOR INCOMING MESSAGE ' 
1994 ERRORMSG X* 0100000000* ,DEST=C*T1" , X 

DATA=C*E MESSAGE TOO LONG • 

2006 * 

2007 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

2008 * QUEUEING WITH OR WITHOUT DISK BACKUP 

2009 ERRORMSG X* 0040000000*, DEST=C*T1* , X 
DATA=C*E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN * 

2021 * 

2022 ERRORMSG X* 0002000000* ,DEST=C*T1" , X 
DATA=C*E FORWARDED TO INVALID DESTINATION • 

2034 ERRORMSG X" 0000400000*, DEST=C*T1"» X 

DATA=C'E INVALID STATION ID AT CONNECT TIME * 
2046 ERRORMSG X* 0000200000*, DEST=C*T1*, X 

DATA=C*E TERMINAL IS IN HOLD STATUS * 
2058 ERRORMSG X* 0000080000", DEST=C*T1* , X 

DATA=C*E MSGTYPE CODE IN HEADER INVALID * 
2070 ERRORMSG X" OOOOOOEOOO" ,DEST=C* Tl* , X 

DATA=C'E A HARDWARE ERROR HAS OCCURRED ' 

2082 * 

2083 * INEND IS REQUIRED AS LAST DELIMITER MACRO OF INCOMING GROUP 

2084 INEND 

2088 * 

2089 *** 

2090 * 

2091 * OUTGOING GROUP OF MESSAGE HANDLER FOR 1050 TERMINAL 

2092 OUTHDR 
2098 * 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19-28 06/07/74 

2099 * THE FOLLOWING MACRO CAUSES EOT LINE CONTROL CHARACTERS TO BE INSERTED 

2100 * IN EACH OUTGOING MESSAGE — SINCE NTBLKSZ= (BLKSIZE) CODED IN THE 

2101 * TERMINAL MACRO — IT ALSO INSERTS EOB CHARS. — THIS PARAMETER COULD 

2102 * ALSO BE PLACED AS AN OPERAND OF THIS MACRO TO OVERRIDE THE NO. 

2103 * SPECIFIED IN THE TERMINAL MACRO 

2104 MSGFORM 

2115 * 

2116 * SINCE ERROR MESSAGES ARE SENT TO THIS TERMINAL — AND THESE COULD 

2117 * INCLUDE THOSE FOR THE APPLICATION TO APPLICATION PROGRAM WHICH 

2118 * WILL NOT HAVE A HEADER AND CANNOT, BE PROCESSED AS A NORMAL OUTPUT 

2119 * MESSAGE TO THIS TERMINAL — CHECK 1ST CHARACTER FOR AN E — THE 1ST 

2120 * CHAR. OF EVERY ERRORMSG — IF NOT E WILL SKIP TO NEXT MSGTYPE MACRO — 

2121 * IF E, WILL PROCESS TO NEXT MSGTYPE MACRO AND THEN SKIP TO NEXT 

2122 ♦ DELIMITER — OUTBUF 

2123 MSGTYPE C'E* 

2139 * 

2140 * SET SCAN POINTER BACK TO BEGINNING OF BUFFER AND INSERT NL CHARACTER 

2141 * AT BEGINNING OF MESSAGE — IDLES WILL BE INSERTED AFTER NL IN OUTBUF 

2142 SETSCAN l,POINT=BACK 
2153 MSGEDIT ( (I.XL1* 15* ,SCAN) ) 

2168 ♦ 

2169 * USE MSGTYPE WITH BLANK OPERAND TO PROCESS OTHER MESSAGES 

2170 MSGTYPE 

2175 * 

2176 * INSERT NL CHARACTER AT BEGINNING OF MESSAGE — IDLES WILL BE INSERTED 

2177 * AFTER NL IN OUTBUF 

2178 MSGEDIT ( (I, XLl'15* .SCAN) ) 

2190 * 

2191 * SET THE SCAN POINTER TO THE PERIOD IN THE HEADER AND INSERT DATE, 

2192 * TIME, AND SEQUENCE NO. — INSERTED IN EBCDIC SO DO BEFORE CODE 

2193 SETSCAN C." 

2206 * 

2207 * IF NO OPERAND — BOTH DATE AND TIME ARE INSERTED — SPACE MUST BE 

2208 * RESERVED BY MEANS OF THE RESERVE= OPERAND OF DCB FOR LINE — THE DATE 

2209 * IS IN FORM — (BLANK) YY.DDD — 7 CHARS. — TIME IN FORM — 

2210 * (BLANK) HH.MM.SS — 9 CHARACTERS 

2211 DATETIME 

2227 * 

2228 * SEQUENCE IN AN OUTHDR SUBGROUP INSERTS SEQUENCE NO. IN FORM — 

2229 * (BLANK) NNNN — 5 CHARS. — SPACE MUST BE RESERVED BY MEANS OF RESERVE= 

®2230 * OPERAND OF DCB FOR LINE 
2231 SEQUENCE 

2241 * 

2242 * LOG OUTGOING HEADERS — USE DCBNAME AS OPERAND — PUT MACRO AFTER 

2243 * INSERTION OF DATE, TIME, AND SEQUENCE NOS. SO THESE WILL APPEAR 
22 44 * IN LOGGED HEADER 

2245 * NEXT IWD DISABLED — * 

2246 * LOG MSGLOC 

2247 * 

2248 * THE MACROS IN THE FOLLOWING SUBGROUP ARE EXECUTED FOR EVERY BUFFER 

2249 * OF THE MESSAGE 

2250 OUTBUF 

2255 * 

2256 * INSERT NL CHAR. FOR EVERY X'FF* CHAR. IN MESSAGE — X'FF' IS THE 

2257 * RECDEL CHAR. SPECIFIED IN THE TPROCESS MACROS 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

2258 MSGEDIT ( (RA,XL1* 15' ,XL1*FF' ) ) 

2276 * 

2277 * INSERT 13 IDLE CHARS. AFTER EVERY NL CHARACTER PLACED IN MESSAGE 

2278 MSGEDIT ( (I, (X* 17* ,13) ,XL1' 15* ) ) 

2295 * 

2296 * TRANSLATE THE MESSAGE FROM EBCDIC TO LINE CODE — IF ISSUED IN A 

2297 * SUBGROUP AND ANY SEGMENTS OF A MESSAGE PROCESSED BY THAT SUBGROUP, 

2298 * THE ENTIRE MESSAGE IS TRANSLATED 

2299 CODE 

2308 * 

2309 * THE OUTMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS IN OUTGOING 

2310 * GROUP — IT IS EXECUTED ONLY AFTER AN ENTIRE BLOCK OR MESSAGE HAS BEEN 

2311 * SENT 

2312 OUTMSG 

2321 * 

2322 * THE HOLD MACRO SUSPENDS TRANSMISSION TO A STATION EITHER FOR A TIME 

2323 * INTERVAL (IF SPECIFIED) OR UNTIL RELEASED BY AN OPERATOR CONTROL 

2324 * MESSAGE — IF NOT USED, MESSAGES THAT CANNOT BE TRANSMITTED ARE 

2325 * TREATED AS THOUGH THEY HAVE BEEN TRANSMITTED — ALSO, A HOLD OPERATOR 

2326 * CONTROL MESSAGE HAS NO EFFECT IF THERE IS NO HOLD MACRO — 

2327 * BITS BEING TESTED BY MASK ARE FOR HARDWARE ERRORS 

2328 HOLD X' 000000E000' 

2340 * 

2341 * IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

2342 * SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

2343 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 

2344 * THE MESSAGE INCLUDES THE HEADER OF THE MESSAGE IN ERROR AND THE 

2345 * ERROR MESSAGE 

2346 * 

2347 * THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

2348 * RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

2349 ERRORMSG X' 8000000000*. DEST=C"T1' # X 
DATA=C*E ERROR IN PROCESSING HEADER * 

2361 * 

2362 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 
2363' * QUEUEING WITH OR WITHOUT DISK BACKUP 
2364 ERRORMSG X' 0040000000", DEST=C*T1* , X 

DATA=C*E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN ' 

2376 * 

2377 ERRORMSG X" 0000400000". DEST=C*T1*« X 
DATA=C"E INVALID STATION ID AT CONNECT TIME * 

2389 ERRORMSG X' 0000200000", DEST=C"T1" , X 

DATA=C*E TERMINAL IS IN HOLD STATUS * 

2401 ERRORMSG X* 0OOO00E00O*.DEST=C" , Tl" , X 

DATA=C*E A HARDWARE ERROR HAS OCCURRED * 

2413 * 

2414 * OUTEND REQUIRED AS LAST DELIMITER MACRO OF OUTGOING GROUP 

2415 OUTEND 
2419 * 
24 20 * A LTORG SHOULD BE CODED AFTER LAST DELIMITER OF EACH MH IF MCP HAS 

2421 * MORE THAN 1 MH 

2422 ' LTORG 

2423 * 
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IOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

2425 *♦* 
2126 ♦ 

2427 * MESSAGE HANDLER FOR INPUT FROM AND OUTPUT TO TWX TERMINAL 

2428 * 

2429 * THE FOLLOWING MACRO IS REQUIRED AND MUST BE FIRST 

2430 * LC= IS THE ONLY REQUIRED OPERAND — 

2431 * OUT SAYS TO REMOVE LINE CONTROL CHARS. 

2432 * IN SAYS NOT TO REMOVE LINE CONTROL CHARS. 

2433 * 

2434 MHTWX STARTMH LC=OUT 

2450 * 

2451 * THE FOLLOWING MACRO IS REQUIRED AS THE FIRST MACRO IN ANY INCOMING 

2452 * GROUP 

2453 INHDR 

2464 * 

2465 ♦ THE FOLLOWING MACRO TRANSLATES FROM LINE CODE TO EBCDIC — MACROS 

2466 * FOLLOWING THIS WILL ACT UPON CHARACTERS IN EBCDIC — IT WILL CAUSE 

2467 * ENTIRE MESSAGE TO BE TRANSLATED EVEN THOUGH IN INHDR GROUP 

2468 CODE 

2488 * 

2489 * LOG INCOMING HEADERS — USE DCBNAME AS OPERAND 

2490 * NEXT IWD DISABLED — * 

2491 * LOG MSGLOG 

2492 * 

2493 * SET SCAN POINTER TO $ 

2494 SETSCAN C $• 

2507 * 

2508 * PROCESS THE REMAINDER OF THE HEADER ACCORDING TO THE MSGTYPE FIELD 

2509 * SPECIFIED NEXT IN THE HEADER — IF THE NEXT FIELD MATCHES THE CHARACTER 

2510 * SPECIFIED IN THE OPERAND, THE MACROS SPECIFIED BETWEEN IT AND THE 

2511 * NEXT MSGTYPE MACRO ARE EXECUTED AND CONTROL IS THEN PASSED TO THE 

2512 * NEXT DELIMITER — IN THIS CASE INBUF -IF THEY DO NOT MATCH, CONTROL 

2513 * PASSES TO THE NEXT MSGTYPE MACRO WHERE THE TEST IS AGAIN MADE 

2514 * 

2515 * IF MSGTYPE IS 1, THIS MESSAGE SHOULD BE FORWARDED TO THE 1050 

2516 MSGTYPE C'l" 

2532 * 

2533 * SCAN POINTER IS AT SOURCE — ISSUE ORIGIN — SINCE THIS IS A SWITCHED 

2534 * LINE, ORIGIN WILL CHECK VALIDITY OF FIELD AND IDENTIFY THE CALLING 

2535 * STATION TO TCAM 

2536 ORIGIN 

2546 FORWARD DEST=C'T1' 

2561 * 

2562 * IF MSGTYPE IS 2, THIS MESSAGE SHOULD BE FORWARDED TO TWX TERMINAL — 

2563 * SEE COMMENTS UNDER MSGTYPE 1 FOR OTHER MACROS 

2564 MSGTYPE C* 2' 
2582 ORIGIN 

2592 FORWARD DEST=C'T2' 

2607 * 

2608 * IF MSGTYPE IS 5, THIS MESSAGE SHOULD BE FORWARDED TO THE COBOL 

2609 * APPLICATION PROGRAM — 

2610 * SEE COMMENTS UNDER MSGTYPE 1 FOR OTHER MACROS 

2611 MSGTYPE C" 5" 
2629 ORIGIN 

2639 FORWARD DEST=C* PIN' 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

2654 * 

2655 * IF MSGTYPE IS 6, THE SOURCE FIELD HAS BEEN OMITTED (IN ORDER FOR 

2656 * THE COBOL PROGRAM TO CHECK THAT THE LINE NAME — T2A — RATHER THAN THE 

2657 * STATION NAME — T2 — IS GIVEN AS SOURCE) — THE MESSAGE IS TO BE SENT TO 

2658 * THE COBOL APPLICATION PROGRAM 

2659 MSGTYPE C'6" 

2677 FORWARD DEST=C , PIN'" 

2692 * 

2693 * IF THE MSGTYPE IS ANYTHING ELSE, IT IS INVALID — SET THE USER ERROR 

2694 * BIT WITH THE TERRSET MACRO — IN THE INMSG GROUP, WE WILL CANCEL MSG. — 

2695 * ISSUE FORWARD MACRO ANYWAY SINCE REQUIRED 
26 96 MSGTYPE 

2701 FORWARD DEST=C*T1* 

2716 TERRSET 

2723 * 

2724 * THE MACROS IN THE FOLLOWING SUBGROUP ARE EXECUTED FOR EVERY BUFFER 

2725 * OF THE MESSAGE 

2726 INBUF 

2731 * 

2732 * SPECIFY THE MAXIMUM NO. OF CHARACTERS ALLOWED IN AN INCOMING MESSAGE 

2733 * — THIS MACRO ALSO CHECKS IF THE INPUT BUFFER IS FILLED WITH IDENTICAL 

2734 * CHARACTERS, USUALLY AN INDICATION OF STATION MALFUNCTION — SETS A 

2735 * BIT IN ERROR RECORD FOR EITHER CONDITION 

2736 CUTOFF 900 

2744 * 

2745 * DELETE EVERY CR CHAR. AND INSERT X'FF* FOR EVERY LF CHAR. — X'FF* 

2746 * IS THE RECDEL CHARACTER SPECIFIED IN THE TPROCESS MACROS (IF MESSAGES 

2747 * WERE ALWAYS GOING TO AN APPLICATION PROGRAM, WE COULD USE DELIMIT 

2748 * INSTEAD OF XLl'FF") 

2749 MSGEDIT ( (RA, CONTRACT, XL1* 26' ), (RA.XL1 "FF' , XL1 * 15' ) ) 

2772 * 

2773 * THE INMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS — IT IS EXECUTED 

2774 * AFTER AN ENTIRE MESSAGE OR BLOCK HAS BEEN PROCESSED — NO EXECUTABLE 

2775 * USER-WRITTEN CODE SHOULD BE INCLUDED IN THIS SUBGROUP 

2776 INMSG 

2784 * CANCELMG CAUSES IMMEDIATE CANCELLATION OF MESSAGE IF ANY ERRORS 

2785 * 

2786 * SPECIFIED BY ITS MASK OCCUR — IF USED, IT MUST BE 1ST MACRO UNDER 

2787 * INMSG — AN ERRORMSG MACRO MAY THEN NOTIFY OF THE ERROR — 

2788 * CANCELMG IF THE USER ERROR BIT IS SET INDICATING THE MSGTYPE FIELD 

2789 * WAS INVALID — BIT20 

2790 CANCELMG X" 0000080000* 

2795 * 

2796 * IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

2797 * SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

2798 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 

2799 * THE MESSAGE INCLUDES THE HEADER OF THE MESSAGE IN ERROR AND THE 
2 800 * ERROR MESSAGE 

2801 * 

2802 * THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

2803 * RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

2804 ERRORMSG X* 8000000000* ,DEST=C" Tl* , X 

DATA=C*E ERROR IN PROCESSING HEADER ° 
2816 ERRORMSG X" 4000000000* „DEST=C*T1« , X 

DATA=C*E INVALID ORIGIN IN HEADER * 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

2828 ERRORMSG X* 0200000000"«DEST=C"T1" , X 

DATA=C*E INSUFFICIENT BUFFERS FOR INCOMING MESSAGE • 

2840 ERRORMSG X" 0100000000". DEST=C*T1« , X 

DATA=C*E MESSAGE TOO LONG ' 

2852 * 

2853 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

2854 * QUEUEING WITH OR WITHOUT DISK BACKUP 

2855 ERRORMSG X* 0040000000"«DEST=C , T1" , X 

DATA=C"E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN • 

2867 * 

2868 ERRORMSG X" 0002000000" ,DEST=C"T1" , X 

DATA=C"E FORWARDED TO INVALID DESTINATION * 
2880 ERRORMSG X" 0000400000* ,DEST=C"T1" , X 

DATA=C*E INVALID STATION ID AT CONNECT TIME ' 
2892 ERRORMSG X" 0000200000" ,DEST=C*T1" , X 

DATA=C*E TERMINAL IS IN HOLD STATUS * 
2904 ERRORMSG X" 0000080000" ,DEST=C"T1" , X 

DATA=C*E MSGTYPE CODE IN HEADER INVALID * 
2916 ERRORMSG X" 000O0OE000" ,DEST=C"T1* , X 

DATA=C'E A HARDWARE ERROR HAS OCCURRED ' 

2928 * 

2929 * INEND IS REQUIRED AS LAST DELIMITER MACRO OF INCOMING GROUP 

2930 INEND 

2934 * 

2935 *** 

2936 * 

2937 * OUTGOING GROUP OF MESSAGE HANDLER FOR TWX TERMINAL 

2938 OUTHDR 

2944 * 

2945 * INSERT CR LF RUBOUT AT BEGINNING OF MESSAGE 

2946 MSGEDIT ( (I, XL3' 261507* , SCAN) ) 

2958 * 

2959 * THE FOLLOWING MACRO CAUSES EOT LINE CONTROL CHARACTERS TO BE INSERTED 

2960 * IN EACH OUTGOING MESSAGE 

2961 MSGFORM 

2968 * 

2969 * SET THE SCAN POINTER TO THE PERIOD IN THE HEADER AND INSERT DATE, 

2970 * TIME, AND SEQUENCE NO. — INSERTED IN EBCDIC SO DO BEFORE CODE 

2971 SETSCAN C»." 

2984 * 

2985 * IF NO OPERAND — BOTH DATE AND TIME ARE INSERTED — SPACE MUST BE 

2986 * RESERVED BY MEANS OF THE RESERVE= OPERAND OF DCB FOR LINE — THE DATE 

2987 * IS IN FORM— (BLANK) YY.DDD — 7 CHARS.— TIME IN FORM — 

2988 * (BLANK) HH.MM.SS — 9 CHARACTERS 

2989 DATETIME 

3002 * 

3003 * SEQUENCE IN AN OUTHDR SUBGROUP INSERTS SEQUENCE NO. IN FORM — 

3004 * (BLANK) NNNN — 5 CHARS. — SPACE MUST BE RESERVED BY MEANS OF RESERVE= 

3005 * OPERAND OF DCB FOR LINE 

3006 SEQUENCE 

3013 * 

3014 * LOG OUTGOING HEADERS — USE DCBNAME AS OPERAND — PUT MACRO AFTER 

3015 * INSERTION OF DATE, TIME, AND SEQUENCE NOS. SO THESE WILL APPEAR 

3016 * IN LOGGED HEADER 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

3017 * NEXT IWD DISABLED--* 

3018 * LOG MSGLOG 

3019 * 

3020 * THE MACROS IN THE FOLLOWING SUBGROUP ARE EXECUTED FOR EVERY BUFFER 

3021 * OF THE MESSAGE 

3022 OUTBUF 

3026 * 

3027 * INSERT CR LF RUBOUT FOR EVERY X'FF' CHAR. IN MESSAGE— X • FF • IS 

3028 * THE RECDEL CHAR. SPECIFIED IN THE TPROCESS MACROS 

3029 MSGEDIT ( (RA.XL3' 261507' .XLl'FF' ) ) 

3047 * 

3048 * TRANSLATE THE MESSAGE FROM EBCDIC TO LINE CODE — IF ISSUED IN A 

3049 * SUBGROUP AND ANY SEGMENTS OF A MESSAGE PROCESSED BY THAT SUBGROUP, 

3050 * THE ENTIRE MESSAGE IS TRANSLATED 

3051 CODE 

3060 * 

3061 * THE OUTMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS IN OUTGOING 

3062 * GROUP — IT IS EXECUTED ONLY AFTER AN ENTIRE BLOCK OR MESSAGE HAS BEEN 

3063 * SENT 

3064 OUTMSG 

3073 * 

3074 * THE HOLD MACRO SUSPENDS TRANSMISSION TO A STATION EITHER FOR A TIME 

3075 * INTERVAL (IF SPECIFIED) OR UNTIL RELEASED BY AN OPERATOR CONTROL 

3076 * MESSAGE — IF NOT USED. MESSAGES THAT CANNOT BE TRANSMITTED ARE 

3077 * TREATED AS THOUGH THEY HAVE BEEN TRANSMITTED— ALSO, A HOLD OPERATOR 

3078 * CONTROL MESSAGE HAS NO EFFECT IF THERE IS NO HOLD MACRO — 

3079 * BITS BEING TESTED BY MASK ARE FOR HARDWARE ERRORS 

3080 HOLD X'000000E000' 

3086 * 

3087 * IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

3088 * SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

3089 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT— 

3090 * THE MESSAGE INCLUDES THE HEADER OF THE MESSAGE IN ERROR AND THE 

3091 * ERROR MESSAGE 

3092 * 

3093 * THE LAST CHARACTER OF THE MESSAGE IS NL— SO THE CARRIAGE WILL BE 

3094 * RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

3095 ERRORMSG X' 8000000000' ,DEST=C'T1' , X 

DATA=C*E ERROR IN PROCESSING HEADER * 

3107 * 

3108 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

3109 * QUEUEING WITH OR WITHOUT DISK BACKUP 

3110 ERRORMSG X' 0040000000* „DEST=C*T1' . X 

DATA=CE PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN ' 

3122 * 

3123 ERRORMSG X* 0000400000'«DEST=C*T1' , X 

DATA=C'E INVALID STATION ID AT CONNECT TIME ' 
3135 ERRORMSG X" 0000200000* ,DEST=C'T1' , X 

DATA=C'E TERMINAL IS IN HOLD STATUS ' 
3147 ERRORMSG X* OOOOOOE0OO* ,DEST=C*T1" , X 

DATA=C'E A HARDWARE ERROR HAS OCCURRED • 

3159 * 

3160 * OUTEND REQUIRED AS LAST DELIMITER MACRO OF OUTGOING GROUP 

3161 OUTEND 



LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

3165 * 

3166 * A LTORG SHOULD BE CODED AFTER LAST DELIMITER OF EACH MH IF MCP HAS 

3167 * MORE THAN 1 MH 
0010C0 3168 LTORG 

3169 * 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT ASM 0102 19.28 06/07/74 

3171 *** 

3172 * 

3173 * MESSAGE HANDLER FOR INPUT FROM AND OUTPUT TO APPLICATION PROGRAM 

317 4 * RUNNING WITH TERMINALS 

3175 * 

3176 * THE FOLLOWING MACRO IS REQUIRED AND MUST BE FIRST 

3177 * LC= IS A REQUIRED OPERAND — PUT' IN* SINCE NO LINE CONTROL 

3178 * CHARACTERS TO REMOVE 

3179 MHTRMAPP STARTMH LC=IN 

3195 * 

3196 * THE INCOMING GROUP HANDLES MESSAGES COMING FROM AN APPLICATION 

3197 * PROGRAM — THE MESSAGES WILL SUBSEQUENTLY BE PROCESSED BY THE OUTGOING 

3198 * GROUP FOR THE DESTINATION TERMINAL 

3199 * 

3200 * THE INHDR DELIMITER IS REQUIRED AND IS ALWAYS 1ST MACRO 

3201 INHDR 

3212 * 

3213 * LOG INCOMING HEADERS — USE DCBNAME AS OPERAND 

3214 * NEXT IWD DISABLED^-* 

3215 * LOG MSGLOG 

3216 * 

3217 * THE FORWARD MACRO IS REQUIRED IN EACH INHDR SUBGROUP — 

3218 * THE OPERAND DEST=PUT SAYS TO FORWARD TO THE DESTINATION SPECIFIED 

3219 * IN THE PREFIX TO THE APPLICATION PROGRAM WORK AREA 

3220 FORWARD DEST=PUT 

3228 * 

3229 * THE INMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS IN AN INCOMING 

3230 * GROUP — IT IS EXECUTED AFTER AN ENTIRE MESSAGE OR BLOCK HAS BEEN 

3231 * PROCESSED 

3232 INMSG 

3240 * 

3241 * IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

3242 * SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

3243 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 

3244 * 

3245 * THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

3246 * RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

3247 ERRORMSG X" 0200000000' ,DEST=C*T1* , X 
DATA=C'E INSUFFICIENT BUFFERS FOR INCOMING MESSAGE ' 

3259 * 

3260 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

3261 * QUEUEING WITH OR WITHOUT DISK BACKUP 

3262 ERRORMSG X« 0040000000* ,DEST=C'T1" , X 
DATA=C'E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN * 

3274 ERRORMSG X' 0002000000". DEST=C'T1* , X 

DATA=C*E FORWARDED TO INVALID DESTINATION • 

3286 * 

3287 * INEND IS REQUIRED AS LAST DELIMITER OF INCOMING GROUP 

3288 INEND 

3292 * 

3293 *** 

3294 * 

3295 * OUTGOING GROUP HANDLES MESSAGES BEING SENT TO APPLICATION PROGRAM 

3296 ' OUTHDR 



© 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19-28 06/07/74 



3302 
3303 
3304 
3319 
3320 
3321 
3322 
3330 
3331 
3332 
3333 
3340 
3341 
3342 
3343 
3344 
3345 
3346 
3347 
3348 
3356 
3357 
3358 
3359 
3360 
3361 
3362 
3379 
3380 
3381 
3382 
3383 
3384 
3385 
3386 
3397 
3398 
3399 
3400 
3401 



DELETE ANY CHARS. SUCH AS CR.LF WHICH APPEAR BEFORE $ IN HEADER 
MSGEDIT ((R.CONTRACT.SCAN.C'S*)) 

SET SCAN POINTER OVER 2 NON-BLANK CHARS. — $ AND MSGTYPE FIELD — SO 
IT POINTS TO BEFORE SOURCE FIELD 
SETSCAN 2 

INSERT SEQUENCE NO.— FORMAT IS (BLANK) NNNN — 5 CHARS—SPACE MUST BE 
RESERVED BY MEANS OF RESERVE= OPERAND OF DCB FOR LINE 
SEQUENCE 

LOG OUTGOING HEADERS — USE DCBNAME AS OPERAND — PUT MACRO AFTER 
INSERTION OF SEQUENCE NO. SO THIS WILL APPEAR IN LOGGED HEADER 

NEXT IWD DISABLED—* 
LOG MSGLOG 



SET SCAN POINTER OVER 2 NON- BLANK CHARS. 
TO EOF FIELD 

SETSCAN 2 



(SOURCE FIELD) SO IT POINTS 



SETEOF IS USED TO IDENTIFY THE LAST MESSAGE OF A GROUP OF MESSAGES 
TO THE APPLICATION PROGRAM — IT CAUSES THE NEXT READ/CHECK AFTER 
THIS COMPLETE MESSAGE HAS BEEN RECEIVED TO PASS TO AN APPLICATION 
PROGRAM EODAD ROUTINE — (THE COBOL PROGRAM WOULD RECEIVE AN ETI 
INDICATION) 

SETEOF C* F' 

NO OUTMSG SUBGROUP WILL BE EXECUTED FOR A MESSAGE BEING TRANSFERRED 
FROM A TPROCESS QUEUE TO AN APPLICATION PROGRAM — 
SO OMIT OUTMSG IN THIS MESSAGE HANDLER 



OUTEND IS REQUIRED AS LAST DELIMITER OF OUTGOING GROUP 
OUTEND 

A LTORG SHOULD BE CODED AFTER LAST DELIMITER OF EACH MH IF MCP HAS 
MORE THAN 1 MH 
LTORG 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19.28 06/07/74 



® 



3403 
3404 
3405 
3406 
3407 
3U08 
3409 
3410 
3411 
3427 
3428 
3429 
3430 
3431 
3432 
3443 
3444 
3445 
3446 
3447 
3455 
3456 
3457 
3458 
3459 
3467 
3468 
3469 
3470 
3471 
3472 
3473 
3474 

3486 
3487 
3488 
3489 



3501 

3513 
3514 
3515 
3519 
3520 
3521 
3522 
3523 
3524 
3525 
3526 
3527 
3528 



* MESSAGE HANDLER FOR COBOL PROGRAMS THAT SIMULATE TERMINAL INPUT DATA 

* —USED FOR TESTING WITHOUT TERMINALS 

* THE FOLLOWING MACRO IS REQUIRED AND MUST BE FIRST 

* LC= IS A REQUIRED OPERAND — PUT" IN* SINCE NO LINE CONTROL 

* CHARACTERS TO REMOVE 
MHAPPAPP STARTMH LC=IN 

* THE INCOMING GROUP HANDLES MESSAGES COMING FROM AN APPLICATION 

* PROGRAM — THE MESSAGES WILL SUBSEQUENTLY BE PROCESSED BY THE OUTGOING 

* GROUP WHEN THE APPLICATION PROGRAM READS THEM BACK 
* 

* THE INHDR DELIMITER IS REQUIRED AND IS ALWAYS 1ST MACRO 

INHDR 
* 

* THE FORWARD MACRO IS REQUIRED IN EACH INHDR SUBGROUP — 

* THE OPERAND DEST=PUT SAYS TO FORWARD TO THE DESTINATION SPECIFIED 

* IN THE PREFIX TO THE APPLICATION PROGRAM WORK AREA 

FORWARD DEST=PUT 
* 

* THE INMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS IN AN INCOMING 

* GROUP — IT IS EXECUTED AFTER AN ENTIRE MESSAGE OR BLOCK HAS BEEN 

* PROCESSED 

INMSG 
* 

* IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

* SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

* 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT— 
* 

* THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

* RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

ERRORMSG X* 0200000000*. DEST=C Tl* , X 

DATA=C'E INSUFFICIENT BUFFERS FOR INCOMING MESSAGE ■ 
* 

* THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

* QUEUEING WITH OR WITHOUT DISK BACKUP 

ERRORMSG X" 0040000000*. DEST=C*T1* , X 

DATA=C*E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN ' 

ERRORMSG X* 0002000000". DEST=C*T1* , X 

DATA=C'E FORWARDED TO INVALID DESTINATION ' 
* 

* INEND IS REQUIRED AS LAST DELIMITER OF INCOMING GROUP 

INEND 



* OUTGOING GROUP HANDLES MESSAGES BEING SENT TO APPLICATION PROGRAM 
* 

* NO OUTMSG SUBGROUP WILL BE EXECUTED FOR A MESSAGE BEING TRANSFERRED 

* FROM A TPROCESS QUEUE TO AN APPLICATION PROGRAM — 

* SO OMIT OUTMSG IN THIS MESSAGE HANDLER 



LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



ASM 0102 19-28 06/07/74 
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3529 
3530 
3541 
3542 
3543 
3544 
3545 
3546 



OUTEND IS REQUIRED AS LAST DELIMITER OF OUTGOING GROUP 
OUTEND 

A LTORG SHOULD BE CODED AFTER LAST DELIMITER OF EACH MH IF MCP HAS 
MORE THAN 1 MH 
LTORG 
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De fi ning the B uffers 



User-defined areas of main storage 
receive any and all messages entering a 
TCAM network. Such areas, known as 
buffers, are used for handling, gueueing, 
and transferring message segments between 
all lines and gueueing media, and between 
gueueing media and COBOL work areas. 
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Three operands of the INTRO macro, (T) , 
describe the TCAM buffer unit pool. As in 
the sample program shown in Figure 160, the 
operands that define the size of buffer 
units and specify the number assigned are 
KEYLEN, LNUNITS, and MSUNITS. The operands 
BOFSIZE, BUFIN, and BUFOUT, given in the 
DCB for line groups, @ , and in the PCB, 
(6) , for an application program, specify 
the buffer size and the number of buffers 
to be assigned initially for a receiving or 
sending operation. The manner in which the 
PCI= operand of the DCB for a line group, 
^9 , is coded greatly affects the number 
coded for LNUNITS in the INT80 macro and 
the numbers coded for the BUFIN and BUFOUT 
operands of the DCB for the line group. 



Activating a nd Dea ct ivating the Message 
Control Program 



The TCAM message control program is 
assembled, link-edited, and executed like 
any other program running under an OS/VS 
system. The macros INTBO, OPEN, and BEADY, 
issued as a group, make up the data-set 
initialization and activation section of 
the message control program. 

Orderly deactivation of the TCAM system 
must stop incoming and outgoing message 
traffic and create a checkpoint record. 
The user must ensure that the data sets for 
any application program using TCAM as its 
access method are closed before the MCP 
enters its deactivation section, which 
closes the MCP data sets. (It is suggested 
that the headers of messages transmitted to 
the COBOL programs contain a code that 



signals the COBOL program to go to the 
STOPRUN statement.) Finally, the MCP 
coding must return control to the OS/VS 
supervisor. 

I NTRO ^Macros As the first macro executed 
in the message control program, INTRO, (?) , 
establishes standard entry linkage, chains 
save areas, provides addressability, and 
saves the start parameter list pointer. (A 
description of the operands in the INTRO 
macro precedes the macro itself in the 
sample program.) 

I2i§" The message below is issued if at 
least one of the following operands is 
omitted from the I NTHO macro: STARTUP^, 
KEYLEN=, LNUNITS= , and (if DISK=YES is 
coded in the INTRO macro) CPB=. 



00 IED002A SPECIFY TCAM PARAMETERS 



The user may then enter the additional 
reguired parameters, changing certain other 
operands as desired. 

OPEN Macro : The OPEN macros, (5), complete 
the initialization of the TCAM data sets 
and activate them for use. The TCAM data 
sets that must be activated in the MCP by 
OPEN macros are those for the message 
gueues, (a) , checkpoint, optionally (d) , the 
line groups, (c) , and the message log, 
optionally®. If a snap dump is used, the 
user must also open the data set for snap, 

©- 

READY Macro : The READY macro, (3) , must be 
the last instruction in the initialization 
and activation section of the MCP. When 
READY has executed, the system is ready to 
handle message traffic. 

£L2S_E_Hacro; An optional snap dump of the 
program begins the deactivation section. 
Then the first CLOSE macro instruction, 
(5) , is executed. This deactivation 
section is not executed until all data sets 
in TCAM application programs have been 
closed. In the example, the user closes 
the line group data sets, (a) , first; next 
the snap data set, (b) ; then the message 
log data set, © ; the checkpoint data set 
next to last, (3) ; and finally the message 
gueues data set, (e) . 

Note: The data sets may be closed in any 
order provided that the checkpoint data set 
and the message queues data set are closed 
in the order indicated. 

RETORN Macro: The assembler -language Load 
instruction is issued to restore register 
13 with the address of the system save 
area, and the RETURN macro, (§) , is issued 
to return control to the OS/VS supervisor. 
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Defining the MCP Dat a Sets, an d Process 
Control Blocks 



The user must provide information that 
serves as an interface between the message 
control program and the application 
program. This information is contained in 
process control blocks (PCB) and is 
generated by the PCB macro. 
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If the user does not open a line and, 
therefore, does not need either a DCB for a 
line group or a TERMINAL entry, the 
assembly of the MCP, nevertheless, 
generates an error message for the 
undefined symbol of IEDQSTCS. The user can 
either define this symbol in this program 
with a dummy label or ignore the severity 
level of (8) in the link-edit step. The 
symbol IEDQSTCS need not be correctly 
defined when the user is running only 
application-to-application programs. 

Either or both of the other two types of 
data sets — the checkpoint data set and 
the log data set — may be specified if 
needed. To describe data sets to the 
system, the user (via a DCB macro) defines 
a data control block (DCB) for each data 
set cited. 

PCB Macro: A process control block, 
created through specification of the PCB 
macro (6^ is required in the MCP for each 
active application program. The PCB macro 
is similar to the DCB for the line groups 
in that it specifies the name of the 
message handler to be used for messages 
being sent by or received from an 
application program, as well as buffer 
requirements. The TPROCESS macro (see the 
discussion under "Defining Terminal and 
Line Control Areas") refers to the name of 
the PCB macro. 

In the sample program given in Figure 
160 are three process control blocks — 
PCBLK, (a) , for a COBOL program running 
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DCB Ma cro: A data control block, created 
through specification of the DCB macro, 
(7) , is required for each data set referred 
to by the MCP. In the sample message 
control program, data control blocks are 
defined as follows: 

• The message gueues DCB macro, which 
defines a data control block for a 
message queues data set, MSGQ (a) , 

* The checkpoint DCB macro, which defines 
a checkpoint data set if the checkpoint 
facility is to be used, CHKPT (b) . 

* The line group DCB macro, which defines 
a line group data set, must be 
specified for each line group in the 
system. In the sample MCP, two line 
group data sets are defined — the 1050 
line group, named LN1050 (c) , and the 
TWX line group, named LNTWX (d) . 

• The log DCB marco, which defines data 
sets for messages or message segments, 
should be specified for each secondary 
storage device on which messages or 
message segments may be logged. In the 
sample program, only one log DCB 
defining the MSGLOG data set, (e) , is 
specified. 

♦ The snap dump DCB macro, which defines 
the data set for a snap dump, should be 
specified only if the user wants a snap 
dump. In the sample program, the DUMP 
data set is defined, (f) . 



Defining T e r ainal and Lin e C ontrol Areas 



In writing an MCP, the user must provide 
information that identifies the remote 
stations, specifies their characteristics 
to the system, and tells how they are to be 
handled. Line control is the scheme of 
operating procedures and signals by which a 
teleprocessing system is controlled. 

Line control concerns itself with such 
tasks as establishing contact between a 
sending and a receiving station, directing 
a message to a specific station on a 
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multistation line, handling priorities when 
two stations try to send at the same time, 
and performing a user-specified action when 
a station fails to respond to a message. 



Several TCAM macr 
user for identifying 
specifying how mess a 
be handled. The TCA 
sample message contr 
Figure 148 -- TTABLE 
TLIST, and TPEOCESS 
Two additional macro 
reserves space for a 
LOGTYPE, needed only 
messages — are also 
user. 



os are available to the 
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s — OPTION, which 
n option field, and 
for logging entire 
available to the COBOL 



TTA BLE Macro : The TTABLE macro, (§) , 
defines the start and the end of the 
terminal table, needed to provide 
information about each station and 
application program. 



UMIIAkJiacro: The TEE 
specified three times in 
program, must be coded f 
that can accept messages 
some terminals that can 
messages) , each group of 
terminals eguipped with 
group-code feature, and 
to stations that do not 
themselves after calling 



SINAL macro, (§) , 

the sample 
or each station 

(as well as for 
only enter 

non-switched 
the hardware 
each switched line 
uniguely identify 

the computer. 



Specification of the TERMINAL macro 
places a station or line name and 
associated information in this terminal 
table. TERMINAL produces a single entry, i 
group entry, or a line entry. In the 
example, the T1 entry, (a) , provides 
information about the 1050 terminal, the 
T2A entry, (b) , information about the 
switched TWX line, and the T2 entry, (c) , 
information about the TWX terminal on this 
line. 



Notes: 

1. The »UTERM=YES° spe 
TERMINAL macro for 
line creates an ent 
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information it need 
stations that call 
the station is iden 
the ORIGIN macro in 
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ry for the line, 
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to the TERMINAL 
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All TERMINAL macros for lines in a 
line group must be arranged in 
ascending relative line numbers. The 
TERMINAL macro for a particular line 
must immediately precede all TERMINAL 
macros for stations on that line. In 
the sample MCP, there is only one line 



per line group and one terminal per 
line, but this need not be true. 

TPRQCE SS .„, Jac.ro : By placing the name of a 
queue for an application program, as well 
as associated information, iiL the terminal 
table, the TPROCESS macro, (ij) , helps 
connect a COBOL program with the message 
control program. 

The user must specify one TPROCESS macro 
for each destination gueue from which a 
COBOL program is to receive messages and at 
least one that is used when messages are 
sent by a COBOL program. (That is, one 
output TPROCESS entry is required for each 
application program running 
simultaneously.) The output TPROCESS entry 
is not the name of a gueue. In the sample 
program, for example, twelve TPROCESS 
entries are specified. The PIN entry, (a) 
, identifies an input destination gueue for 
a COBOL program running with terminals; 
POUT identifies an output process entry. 

Similarly, the PI, (c) , and P2, (d) , 
entries identify input destination queues 
for COBOL programs that simulate terminal 
input data, and the P00T1, (e) , entry 
identifies an output process entry for such 
COBOL programs. The PQ1, PQ2, PQ3, PQ4, 
PQ5, PQ6, and PQOUT TPROCESS entries are 
used for COBOL programs that employ the 
gueue structure feature. 

Note: Because the PIN and POUT entries in 
the example refer to one process control 
block (PCBBLK) and the P1, P2, and PO0T1 
entries refer to another process control 
block (PCBBLK1) , a program running with 
terminals can run concurrently with another 
program. This is also true of the PQ 
entries, which refer to PCBLK2. 

TLIST Macro: An instruction that places 
the name of a list of a single, a group, or 
a process entry_ in the terminal table, the 
TLIST macro, (Tj) , must be specified for 
each such list to be created. This list 
can be specified as either a distribution 
list or a cascade list. When a message is 
sent to a distribution list, the same 
message is sent to all locations on the 
list. When a message is sent to a cascade 
list, the message is transmitted to the 
listed destination with the fewest messages 
enqueued. In the sample message control 
program, the TLIST entry D.1, (a), 
represents a distribution list entry. The 
list should not include a TPROCESS entry 
for a COBOL application program. 

INV| i I§T_ i Macro: An instruction that creates 
an invitation list entry containing the 
invitation characters for the stations on 
the line (in the order in which they are to 
be invited to send messages), the IN7LIST 
macro, (12) , must be issued for each line 



428 



in the system. However, one INVLIST aacro 
suffices for all output-only lines to 
stations that do not use invitation 
seguences. Two INVLIST entries — 
LIST1050, (a) , and LISTTSX, (b) — appear 
in the sample program. 

jlote: Either a parameter of ♦ in the 
INVLIST macro or an operator control 
command (see the section "Using TCAH 
Service Facilities" in this chapter) must 
initially activate a station for entering 
messages. 

In the entry LIST 1050, for example, *T1 
♦ 6215' indicates that the IBH 1050 
terminal identified as T 1 is active for 
entering messages. (6215 is the IBM 1050 
transmission code representation of the 
polling characters A0 in hexadecimal 
notation.) Accordingly, the symbol •T2A*' 
in the LISTTHX entry indicates an initially 
active line. {Note; The terminal name for 
the line, not the station, must be used.) 
For a TWX station, the •-*■* character would 
be followed by an ID seguence instead of 
the polling character used in the LIST1050 
example. In the example, no ID seguence is 
given. The (CPUID) = operand in the 
INVLIST macro for the TWX terminal is 
reguired. 



Designin g the Message Handler 
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A message handler (MHTWX) for input 
from and output to the Teletypewriter 
Exchange (TWX) . 



A message handler (MHTRHAPP) for input 
from and output to an application 
program running with terminals. 



A message handler (MHAPPAPP) for input 
from and output to an application 
program that simulates terminal input 
data. This type of message handler can 
be used for testing without terminals 
or for handling messages sent from one 
application program to another, as in 
the sample COBOL programs TESTTP1 (see 
Figure 163) and TESTTP2 (see Figure 
164) . 



Two kinds of macro instructions that may 
be included in a message handler are 
functional macros and delimiter macros. 
Fun ctional macros perform the specific 
operations necessary for messages directed 
to the message handler. De limi ter macros 
classify and identify seguences of 
functional macro instructions and then 
direct control to the appropriate seguence. 
Figure 149 shows some of the functional 
macros that can be used with the delimiter 
macros in the incoming group and the 
outgoing group of the message handler. All 
of these macros are included in the sample 
message handler in Figure 160. 

To decide which macro to place in which 
group, the user must understand which group 
is executed when. This is discussed in the 
description associated with Figure 159. 
The steps executed by a message handler are 
shown at the right-hand side of this 
figure. When messages are received from 
stations, the incoming group of a message 
handler for the line is executed before the 
outgoing group. However, when messages are 
sent to application programs, the outgoinq 
group of the message handler for the 
application program is executed first. The 
decision boxes shown in Figure 159 are 
determined by the destination specified in 
the reguired FORWARD macro of a message 
handler (that is, if the destination is the 
name of a TPROCESS entry, processing is 
reguired in an application program; if, 
however, the destination is the name of a 
TERMINAL macro, no more processing is 
reguired) . 



A message handler (MH1050) for input 
from and output to the IBM 1050 Data 
Communications System Terminal. 



Note: For descriptions of other macros 
that can be coded in an MCP, see the 
publication QS/7S, TC&M Programmer's Guide. 
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START8H* 



INHDR* 



INBOF 
INMSG 

INEND* 



OOTHDfi 

OOTB OF 

OOTHSG 
OOTEND* 



CODE 

LOG 

SETSCAN 

MSGTYPE 

ORIGIN 

FORWARD 

TERRSET 

COTOFF 
MSGEDIT 

CANCELMG 
ERRORMSG 



MSGFORM 
MSGTYPE 
MSGEDIT 
SETSCAN 
DAT ET I ME 
SEQOENCE 
LOG 
SET EOF 

MSGEDIT 
CODE 

HOLD 
ERBORMSG 



♦The STASTMH macro is always required. 
If the message handler is to handle 
incoming messages, the INHDR, INEND, and 
OOTEND macros are also required. If the 
message handler is to handle outgoing 
messages, the OOTEND macro is required. 

i : j 

Figure 161. Macros that can be coded in a 
Message Handler 



A discussion of sample message handlers 
for terminal line groups appears below. 
For discussions of the MHTRMAPP and 
MHAPPAPP message handlers, see the sections 
"A Message Handler for an Application 
Program Running with Terminals" and "A 
Message Handler for an Application Program 
that simulates Input Data." 



A MESS AGE,, HANDLER, FOR ,?»%, TERMINAL LINE 
G RO O P§ : Because the message handlers for 
the 1050 line and the TWX line are similar 
(except for the difference in line control 
characters and the use of the 1050 for 
error messages) , the description of the 
message handler for the 1050 (MH1050) given 
below should also suffice for the TUX line 
group (MHTWX). 



The Inco ming Group : The first macro in the 
MH1050 message handler is STARTMH, Q , 
in which the LC=O0T operand specifies that 
line control characters are to be removed. 
The first macro in the INHDR, @ * 
subgroup {CODE) , ^§) , translates the 
incoming messages to EBCDIC. Then the LOG 
macro, ([$) , records the header on the log 
data set. Even though the CODE macro is 
part of the INHDR subgroup, all buffers of 
the message are translated from line code 
to EBCDIC — not just the first (header) 
buffer. In the normal case, unless the 
line code is EBCDIC, the CODE macro should 
be placed first, as in this example. A 
CODE macro must be issued before an ORIGIN 
macro, since the name in the header is 
checked against the terminal names, which 
are in EBCDIC. The name in the header, 
therefore, cannot be located unless it has 
first been translated. The same 
translation requirements apply to such 
macros as SETSCAN, ^J) , in the example. 
In this case, if the C'$» in the message 
were not first translated to EBCDIC, the 
C*$' would have to be specified in line 
code. 

The SETSCAN macro, (O) , sets the scan 
pointer to "$ M in the header, and the 
MSGTYPE macros, (£& , that follow check 
the character in the next field (with 
fields separated by at least one blank 
character) for one of the four codes that 
represent possible message destinations. 
If the scan yields a match between a field 
in the incoming message and the code for 
one of the MSGTYPE macros, the macros 
between this MSGTYPE macro and the next 
MSGTYPE macro are executed. Control is 
then given to the next subgroup (INBOF), 

(f|) . When a MSGTYPE match is found, the 
ORIGIN macro, (ij) , is issued. The 
FORWARD macro, (|(5) , which is always 
required, transmits the message to the 
destination specified. 

If there is no match with any of the 
operands specified in the MSGTYPE macros, 
the last MSGTYPE macro, which has a blank 
operand field, is executed. The required 
FORWARD macro follows, and the TERRSET 
macro, (fj) , sets the user error bits in 
the error record for the message. 

In the INBOF subgroup, @ , the COTOFF 
macro, @) , limits the size of the 
incoming messages and checks for station 
malfunction. The insertion of the RECDEL 
character by the MSGEDIT macro, Qy 
allows for record delimiters in the 
message, needed when the COBOL program 
reads in segment mode. The INMSG subgroup, 
^§) , checks the error bits in the error 
record for this message and either cancels 
the message via the CANCELMG macro, @ , 
and/or sends an error message to the^OSO 
terminal using the ESRORMSG macro, (27) . 



430 



The IN END macro, (|J) , a required 
delimiter macro, signifies the end of the 
incoming groups. 

The Outgoing Group : The macros discussed 



translates from EBCDIC to line code when no 
more handling is required with macros that 
operate in EBCDIC. 
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For every error message, the SETSCAN 
macro returns the scan pointer to the 
beginning of the message, and the HSGEDIT 
macro inserts the "NL M character before the 
message text. Processing of error messages 
resumes in the OUTBOF subgroup, @ , of 
the message handler. 



For the non-error mes 
macro also inserts M NL M 
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In the OUTBOF subgroup, QJ) , of this 
message handler, the HSGEDIT macro inserts 
an "NL" character for every record 
delimiter character in the message. 
Because in the incoming group the RECDEL 
character is inserted for every "NL" and 
W LF W character, for a message that is 
simply transmitted from one terminal to 
another the message handler appears to send 
the same line control characters it 
receives. For a message sent by a COBOL 
program, on the other hand, wether or not 
record delimiter characters remain depends 
on the mode specified in the RECEIVE or 
SEND statement. (That is, when the 
programmer receives a message in segment 
mode, the record delimiter character is 
removed; when the programmer receives a 
message in m essage mode, the record 
delimiter is not removed. Accordingly, 
when the programmer sends a message in 
segment mode, the record delimiter 
character is added; when the programmer 
sends a message in message mode, the record 
delimiter is not added. f The next MSGEDIT 
macro inserts 13 idle characters after 
every "NL* 1 character placed in the message, 
to allow the terminal sufficient time to 
return its carriage before receiving the 
next line. Finally, the CODE macro 
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subgroup (see "The 
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TEND macro, @ , 
of the outgoing group. 



A MESSAGE HANDLER FOR AN AP PLICATI ON 
PROGRAM RU NNING WITH TERMINALS : T he 
MHTRMAPP message handler handles messages 
transmitted by a terminal for the 
application program that is sending and 
receiving messages from terminals. Like 
the message handler discussed earlier, 
MHTRMAPP includes both an incoming group 
and an outgoing group. 
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The next SETSCAN macro sets the scan 
pointer over the source field in the header 
so that it points instead to the EOF field. 
The SETEOF macro identifies the last 
message in a data file being processed by 
an application program. If the character 
specified at the location pointed to by the 
scan pointer (and given as an operand in 
the SETEOF macro) is "F", the first RECEIVE 
statement issued by the COBOL program after 
receipt of the message causes the MCP to 
enter an application program SODAD routine. 
As far as the COBOL user is concerned, this 
section sets the "ETI" indicator in the 
field referred to by the END KEY clause in 
the input communication description (CD) . 
The OBTMSG subgroup is not included in this 
message handler because it is not executed 
for messages sent to an application 
program. Nevertheless, the OUTEND 
delimiter macro signifies the end of the 
outgoing group. 
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The macros in the incoming group of this 
;sage handler, headed by the INHDR macro, 
, are executed when messages are 
received from the COBOL program. The LOG 
macro records the information contained in 
the header, and the FORWARD macro, which is 
always reguired, specifies "DEST=PUT" as 
the message destination. This will cause 
the message to be forwarded to the 
destination the COBOL program has indicated 
in the output CD. The INMSG subgroup that 
follows checks to see whether sufficient 
buffer units are available for the message 
and verifies that the destination specified 
is valid. The INEND delimiter macro then 
specifies the end of the incoming group. 

A_M^MI^AlPJLEJ^F01_M_A£EJdICAIIQl 
PROG RAH „TB~ AT SIMUL ATES TERMINAL INPUT_DATA : 
The MHAPPAPP message handler is for 
messages having no header. As a result, 
the only macro in the outgoing group is the 
delimiter macro OUTEND, G9) , which is 
always reguired. 

The incoming group contains both the 
INHDR, WO) , subgroup, containing the 
reguired FORWARD macro, and the INHSG 
subgroup, which checks for availability of 
sufficient buffer units and verifies that 
the destination specified is valid. The 
reguired INEND delimiter macro is present. 



TCAM commands to the MCP, where they are 
acted upon by a combination of TCAM and 
COBOL- provided code. 



Operator command communication with TCAH 
is accomplished through two special 
TPROCE SS entries and an associated PCB 
defined in the MCP for each COBOL 
application program that will execute 
ENABLE/DISABLE statements. These entries 
are accessed by the COBOL library via the 
special DD names, COBOPIN and COBOPOUT. 
COB0PO0T will be used to issue operator 
commands to TCAM while COBOPIN will be used 
to receive the response messages. 



The TPROCESS entry corresponding to 
COBOPOUT must be identified as a secondary 
operator control station (TPROCESS macro 
option, SECTERM=¥ES) and must indicate the 
TPROCESS entry associated with COBOPIN as 
the destination for operator command 
response messages (TPROCESS macro option, 
ALTDEST=tprocessname) . The message handler 
for the TPROCESS entry associated with 
COBOPOUT must include a TCAH CODE macro 
followed by a TCAM FORWARD macro specifying 
the TPROCESS entry associated with COBOPIN 
in its destination list (to provide a 
response to commands for which the operator 
control character string is invalid — i.e., 
not caught by the CODE macro). 



ANS STANDARD MCP REQUIREMENTS 



If the MCP to be written is to confori 
with the 1974 ANS COBOL standard, using 
ENABLE/DISABLE, SEND ADVANCING, SEND to 
multiple destination, and automatic 
communications job scheduling, then the 
sample MCP shown in Figure 160 must be 
modified as follows. 



ENABLE/DISABLE: Operator Command Interface 



The operator commands used to effect 
ENABLE/DISABLE INPUT (with or without 
terminal) require the job name of the TCAM 
MCP (i.e., the name specified on the JCL 
JOB card for the MCP) . The COBOL object 
time library contains an eight-byte control 
section, ILBOMCPN, that provides the value 
for the MCP job name. The default value of 
the job name is "TCAM". If a different 
name must be used for the HCP, ILBOMCPN 
must be replaced with a control section 
containing the correct value. Figure 162 
illustrates a sample procedure for 
replacing the MCP job name CSECT. 



The ENABLE/DISABLE statements are 
implemented by COBOL by sending various 
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FIXHCPN JOB ... 

// EXEC ASMFCL,PASM.ASM=»NODECK,OBJ» , 

// PARM . L KE D= • LIST, LET, XB EF , NCAL, HE NT • 

//ASM. SYSIN DD * 

ILBOHCPN CSECT 

DC CL8»mcpname» MCP JOB NAME 

END 



DS N= SYS 1 . COBLIB, DISP=OLD 

* 



/* 

//LKED.SYSLHOD DD 
//LKED. SYSIN DD 

INCLUDE SYSLMOD(ILBONBL) 

ALIAS ILBONBLO 

NAME ILBONBL(R) 
/* 

Figure 162. Replacing the MCP Jobname CSECT 



ENABLE/PIS ABLE— KEY Phrase 



The CONTROL option of the TCAM MCP INTRO 
macro must specify a value for the operator 
control string of from one to eight 
characters in length. Optionally, the MCP 
Terminal Table may contain the following 
definition: 



COBOPTO OPTION CLn 

where n may be in the range of one to ten 
but must be at least as large as the length 
of the operator control string specified in 
the INTRO macro. 

Any Terminal Table entry corresponding 
to a symbolic input queue, symbolic source, 
or symbolic destination that may be enabled 
or disabled may have a value specified for 
the COBOPTO option. The value must begin 
with the operator control string and may be 
followed by any characters valid in an 
option field. (Note that the value will be 
padded with spaces on the right if less 
than n characters are specified.) 
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compared to the value of the COBOPTO 
option. 

The key is considered invalid if it does 
not constitute a valid operator control 
string or does not match the COBOPTO field, 
if specified. 

COBOL provides two levels of password 
protection: 

1. The first eight characters of any key 
translate into a TCAM operator control 
string. The control string may be 
considered a "global" password. 

2. The full key value is compared with 
the value of the COBOPTO option field. 
It may be considered a "local" 
password. 

Note that by omitting the COBOPTO option 
field from a Terminal Table entry 
definition, the entry becomes accessable to 
any key translating into a valid operator 
control string (i.e., only "global" 
protection is provided). 

Since more than one terminal table entry 
may be affected by a single ENABLE/DISABLE 
statement containing a single key value, 
all such entries must be accessable via the 
same key. 

The key is validated for all input 
queues and sources or all output 
destinations prior to any actual enabling 
or disabling. 



The value of the oper 
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ENABLE/DISABLE INPUT TERMINAL 



If this form of ENABLE/DISABLE is to be 
executed by COBOL application programs, the 
TCAM MCP Terminal Table must contain the 
following option field definition; 
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C0BOPT1 OPTION FL1 



The Terminal Table entry corresponding to 
each symbolic source that may be enabled or 
disabled must have one of the following 
values specified for the C0B0PT1 option 
field: 

0: the symbolic source is initially 
enabled 

1: the symbolic source is initially 
disabled 

In addition, the following COBOL macro must 
be coded preceding the first INMSG subgroup 
of any MCP message handler that processes 
messages from a symbolic source that may be 
disabled: 



[symbol ] ILBONBLT 
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If the C0B0PT1 option field is not 
specified for the Terminal Table entry 
corresponding to a symbolic source that is 
to be enabled or disabled, the entry is 
considered to be improperly defined and the 
symbolic source is consequently unknown (CD 
STATUS-KEY = ^Q 1 ). 



In addition, the following COBOL macro 
must be included in the initialization 
section of the TCAM MCP (i.e., between the 
INTRO and READY macros) : 

[ symbol] ILBONBLQ [TPRFD= {YESJNO} ] 
,[TLCBD={YES|NO) ] 
,[TAVTD={YES|NO| ] 
,[REGS=[YES|NO} ] 

The parameters TPHFD, TLCBD, and TAVTD 
refers to the TCAM descriptive macros of 
the same name for the Buffer Prefix, Line 
Control Block, and Address Vector Table 
DSECT's, respectively. If YES is coded for 
these parameters, the macro expansion will 
contain those portions of the corresponding 
DSECT's required by the ILBONBLQ macro. NO 
should be coded if the DSECT's are 
generated elsewhere in the MCP. 

If REGS=YES is coded, general register 
usage within the macro expansion will 
appear symbolically as RO through R15 (this 
will cause all register usage to appear in 
the cross reference listing at the end of 
the MCP assembly listing). Assembler 
statements equating these values to actual 
register numbers must be provided elsewhere 
in the MCP. 

The ILBONBLQ macro intercepts control 
during TCAM message enqueuing and 
suppresses enqueuing for disabled symbolic 
input queues. 

If the C0B0PT2 option field is not 
specified for the Terminal Table entry 
corresponding to a symbolic input queue 
that is to be enabled or disabled, the 
entry is considered to be improperly 
defined and the symbolic input queue is 
consequently unknown (CD STATUS-KEY = 
'20'). 



ENABLE/DISABLE INPUT .(without TERMINAL) 



ENABLE/DISABLE OUTPUT 



If this form of ENABLE/DISABLE is to be 
executed by COBOL application programs, the 
TCAM MCP Terminal Table must contain the 
following option field definition: 

COBOPT2 OPTION FL1 

The Terminal Table entry corresponding to 
each symbolic input queue that may be 
enabled or disabled must have one of the 
following values specified for the COBOPT2 
option field: 

0: the symbolic input queue is 
initially enabled 

1: the symbolic input queue is 
initially disabled 



If this form of ENABLE/DISABLE is to be 
executed by COBOL application programs, the 
TCAM MCP must contain a HOLD macro. If the 
HOLD macro is not required by the logic of 
the MCP, a HOLD macro must be coded 
specifying an impossible combination of 
errors in the mask associated with the 
message error record (see the description 
of the Hold/Release Facility in the OS/TS 
TCAJ Programmer's Guid e) . 

The Terminal Table entry corresponding 
to a symbolic destination that may be 
disabled must not specify ma in- storage-only 
queuing. The line corresponding to the 
symbolic destination must be open at the 
time the DISABLE OUTPUT statement is 
executed and may not be opened idle. If 
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these conditions are not met, the symbolic 
destination is considered to be improperly 
defined for the operation and, hence, 
unknown (CD STATOS-KEY = «20'). 



characteristics are to be specified must 
contain a value for the C0B0PT3 option 
according to the following (note that the 
values are given in hexadecimal notation to 
agree with the definition of C0BOPT3) : 



Specif yi ng Characteristics for S ymbolic 
D estinations 



The following characteristics are 
associated with each symbolic destination: 

• Whether or not vertical positioning is 
supported. 

• For devices supporting vertical 
positioning, whether or not page 
psoitioning (Forms Feed) is supported. 

• Whether or not the device has a fixed 
line size. 

• For devices with a fixed line size, 
the size of the line. 

• Whether or not record delimiter 
characters are to be inserted between 
message segments (for this 
characteristic to be effective, the 
BECDEL option of the TPHOCESS entry 
corresponding to the COBTPOOT BD card 
must specify a non-zero value). 

• Whether or not a test should be made 
for a disabled destination condition 
during the execution of each SEND 
statement (CD STATOS-KEY = •10»). 
Specification of this characteristic 
will incur an execution-time 
performance degradation and should be 
used only when the knowledge that the 
destination is disabled is significant 
to COBOL application programs sending 
messages to it. 

The default characteristics for any 
symbolic destination are: 

• no vertical positioning 

• no fixed line size 

• insert record delimiters between 
message segments 

• no test for disabled destination 

If characteristics are to be specified 
for symbolic destinations, the TCAH MCP 
Terminal Table must contain the following 
option field definition: 

C0B0PT3 OPTION XL 11 

Terminal Table entries corresponding to 
symbolic destinations for which 



Bytes 1-8 

X'C3D6C7D6D7E3F373» (This is the hex 
value for •C0B0PT3=* which makes this 
option self-identifying.) 



Byte 9 

Destination characteristics byte: 

Bit (X«80») 

If on, vertical positioning is 
supported for this destination. 
When the ADVANCING clause is 
specified or implied, NL (new 
line) , CS (arrriage return) and/or 
FF (forms feed) control characters 
will be inserted into the message 
by COBOL. If off, the ADVANCING 
clause will be ignored by COBOL. 

Bit 1 (X»40») 

(Meaningful only if bit is on) If 
bit 1 is on, FF (forms feed) will 
be inserted for an ADVANCING PAGE 
request. If off, NL (new line) 
will be inserted for an ADVANCING 
PAGE request. 

Bit 2 (X*20») 

If on, this device has a fixed line 
size (as specified in bytes 10-11); 
COBOL will do automatic line 
folding. If off, no automatic line 
folding will occur. 

Bit 3(XM0«) 

If on, a record delimiter character 
(if available) will be inserted by 
COBOL between message segments. 

Bit 4 (X»08») 

If on, a test will be made to 
determine if this destination is 
disabled daring te execution of 
each SEND statement. If off, no 
test will be made. 

Bits 5-7 (X»07») 
(Reserved) 

Bytes 10-11 

The line width, for fixed line size 
destinations (e.g., if the line width 
is to be 96, code (x^OeO 1 )- For 
variable line size destinations, code 
X'OOOO 1 . 

To conform with the requirements of ANS 
1974 COBOL, the following is required: 

* bit must be on for destinations 
which support vertical positioning. 
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bit 1 must be on for destinations 

which support forms feed- 
bit 2 must be on, and bytes 10-11 must 

be non-zero, for destinations which 

have fixed line sizes- 
bit 3 must be off. 
bit 4 must be on. 



delimiters) specified by information 
provided in the SEND statement ADVANCING 
clauses associated with the messages and 
the value of the COBOPT3 option fields for 
the destinations. Figure 163 illustrates 
the results of executing a sequence of SEND 
statements for a destination supporting 
both vertical positioning and a fixed line 
size. 



If vertical positioning has been 
specified for a destination (COBOPT3 byte 
9, bit on) , the ADVANCING clause of the 
SEND statement causes COBOL to produce 
standard formatted messages containing text 
data, record delimiters, and the three 
EBCDIC/SNA control characters NL (new 
line), CE (carriage return), and FF (forms 
feed). Any specific device-dependent 
formatting required {e.g., insertion of 
idle characters) must be provided in the 
appropriate TCAH MCP message handlers. 

When a SEND statement is executed that 
has an associated end of message (EMI) or 
end of group (EGI) indicator, the assembled 
messages for the destinations identified in 
the CD DESTINATION-TABLE are sent to TCAM. 
The contents of the messages will be a 
composite of text data and control 
characters (NL, CR, FF, and record 



Co mmunications J ob Scheduling (CJS) 



It is sometimes desirable to schedule a 
COBOL object communications program only 
when there is work available for it to do 
(for example, to process messages which are 
entered infrequently or at unpredictable 
times) . For this reason, a utility 
Communications Job Scheduler (CJS) is 
provided. This utility will monitor each 
of a set of user-specified TCAM queues, and 
schedule a user-specified job (using the 
OS/VS START command) when a user-specified 
number of messages is reached. The utility 
is itself a COBOL program, and thus may be 
readily modified to accomodate more 
complicated scheduling requirements (e.g., 
based on time-of~day, or overall system 
load) . 
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SEND # 
1 
2 
3 
4 



Msg. Text 


End Ind. 


Advancing Clause 


Comments 


ABCDEF 


'0' 


After page 


Partial segment, advancing ignored 


GH 


ESI 




"After Advancing 1 line" implied 


UK 


ESI 


Before page 


No advancing between segments 


LMNO 


EMI 


Before lines 





Segment 1 



Segment 2 



Segment 3 



(NL) ABCD (NL) EFGH (RD) (CR) UK (FF) (RD) LMNO (CRJ 

A A A A A A A 

New line character 
inserted because of 
implied advancing 
clause of SEND #2. 

Inserted because of I 

fixed line length. I 

Record delimiter character 
inserted because of segment 
boundary after SEND #2. 

Carriage return character 
inserted because each message 
or message segment for a fixed 
line size destination must 
begin at the leftmost character 
position of the physical line. 

Forms feed character inserted 
because of advancing clause of 
SEND #3. (If forms feed was not 
supported for the destination, 
a new line character would have 
been inserted.) 

Inserted because of segment boundary after SEND #3. | 

Carriage return character inserted because of advancing clause of SEND #4. 

Note: Assume COBOPT3 has specified vertical positioning, forms feed, fixed line size of 4 bytes, and insert record delimiters. 



Figare 163. Example of Message Foraation for a Fixed Line size Destination supporting 
Vertical Positioning 



P reparing the CJ S: The following steps may 
be used for installing and tailoring the 
CJS utility: 

1. The source code for CJS (aodule name 
ILBOCJS) is extracted froa the COBOL 
installation tape by following the 
standard installation procedures. 
(See OS/VS CO BOL Installa t io n 
Referen ce Material, Order No. 

SC2 8-64 81) . 

2. If desired, this source code may be 
modified to meet special local 
requirements (e.g., to change the 
PROGBAM-ID, to change scheduling 
criteria, to provide error recovery, 
etc.) . 

3. The source code should then be 
compiled and link-edited using normal 
local options for COBOL programs. The 



resulting load module must be placed 
in an authorized library with an 
authorization code of one (see the 
description of the Authorized Program 
Facility (APF) in the relevant VS 
Planning and Use Guide). 

4. The TCAM BCP must contain a Terainal 
Table TPROCESS entry for "SYSCJS" and 
an associated PCB. Starting and 
ending messages will be directed to 
this entry by COBOL when a scheduled 
job starts and ends. 

5. JCL should be coded for the CJS. 

6. A special reader procedure, COBURDR, 
must be added as a member of 
SYS1.PEOCLIB. The source for COBURDR 
is extracted from the COBOL 
installation tape by following the 
standard installation procedures {see 
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OS/ YS C OBO L Instal lation Reference 
Materia l) . 



Column 1 

Record identifier: 



mst be "Q". 



7. The partitioned data set identified by 
the COBDBDB reader procedure DD card, 
IEFRDER, must contain a member for 
each job name specified on a CJS Queue 
Polling Record (see "Using the CJS" 
below). Each member contains the JCL 
required to execute the COBOL program 
that will process the gueue causing 
the scheduling to occur, The PARM 
option of the EXEC card for the COBOL 
program must identify the complete 
gueue structure name corresponding to 
the TCAM gueue: 

PAR M= {. - . /QUEUE (g-name 

[ ,sub-g-1-name[ ,sub-g-2-name 
[ ,sub-g-3-name]]3)) 

The member must also contain DD cards 
allowing the COBOL program to access 
the scheduling TCAM queue and to write 
the starting and ending messages to 
the CJS. 

Us ing t he CJS: To execute the CJS, control 
records must be provided specifying the 
gueue polling requirements and the jobs to 
be started. They ha ye the following 
format: 

Haader Record (one only; must be first 
record) 



Column 1 

Record identifier: 

Columns 2-6 



must be "H«. 



Number of seconds to wait between 
pollings: this number indicates 
the number of seconds (of elapsed 
time) that CJS should wait between 
the time it polls all gueues and 
the time it does so again. 

Columns 7-11 

Number of repetitions: this number 
indicates how many times the 
pollings (followed by the wait) 
should take place before CJS 
automatically completes. 

Queue Polling Record 



Columns 2-9 

Queue Name: the name of a TCAM 
queue that is to be polled. 



Columns 10-17 

Job name: specifies the name of a 
member in the partitioned data set 
identified by the IEFRDER DD card 
in the COBURDR reader procedure 
that contains the job to be 
scheduled when the message count 
limit is reached for the 
corresponding queue. 



Column 18 

Association code: 
code which may ass 
more Queue Polling 
polling entry caus 
scheduled, that po 
all other entries 
association code w 
re-polled until an 
is received from t 
This facility is u 
that two jobs are 
the same time to p 
TCAM gueue. 



an alphanumeric 
ociate two or 

Records. When a 
es a job to be 
lling entry and 
with the same 
ill not be 

ending message 
he scheduled job. 
seful in assuring 
not scheduled at 
rocess the same 



Columns 19-23 

Message count limit: when the 
number of completed messages on the 
polled queue reaches or exceeds 
this value, the associated job will 
be scheduled. 

(The value specified for the OCCURS 
clause for "POLL-ENTRY" in the CJS program 
must be large enough to provide an entry 
for each queue polling record) . 

If the CJS terminates successfully, a 
return code (completion code) of zero is 
given. However if an error condition is 
detected, a return code of eight is given. 

Figure 164 illustrates the CJS 
scheduling process. 

Figure 165 provides an example of CJS 
control records and JCL for a 
communications job scheduling application. 
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/ 



TCAM QUEUES 



\ 



queuename-1 



queuename-2 



queuename-n 



SYSCJS 



CJS 



•Read control cards 

• Get queue counts 

• Schedule programs 

"START COBURDR. SYSCJS, 
PROCNAM=jobname-i" 

•Receive "STARTED" and 
"ENDED" messages 



| queuename-n 
| queuename-2 



\ 



queuename-1 
jobname-1 



SYS1 PROLIB 



User JCL Library 





COBURDR 



Read member "jobname-i" of 
partitioned data set identified 
by IEFRDER DD card into system 
job queue. 



jobname - i 



//jobname-i JOB, . . . 

// EXEC PGM= . . . , 

// PARM= ' . . . /QUEUE (queuename-ii) 

•COBOL object-time library 
sends "STARTED" and 
" ENDED " me s s age s . 



Figure 164. Coaaunications Job Scheduling 
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In S ystem Header 



//CJS 


JOB 


• • • 


// 


EXEC PGM=ILBOCJS 


//STEPLIE 


I DD 


DSN=SYS1.C0BLIB,DISP=SHR 


//SYSTPIN 


f DD 


QNAME=SYSCJS 


//SYSOUT 


DD 


SYSOUT=A 


//SYSIN 


DD 


* 


H0001000360 




QQUEUE1 


JOB1 


00001 


QQUEUE2 


JOB2 


A00004 


QQUEUE3 


JOB3 


A00005 


/* 







In SYS1.PBOCLIB 

//COBURDR PROC 



//IEFRDER DD DSN=userlib . . . 

(see OS/VS COBOL Instalation Reference 
Material) 



In_Userlib 


Member: 


J0B1 


//JOB1 

// 

//SUBQ1 


JOB 

EXEC 

DD 


Member: 


JOB2 


//JOB2 

// 

//SUBQ2 
//SUBQ3 


JOB 
EXEC 
DD 
DD 


Member: 


JOB3 


//JOB3 

// 

//SUBQ2 
//SUBQ3 


JOB 
EXEC 
DD 
DD 



PGM = . .. ,PARM='/QUEUE(SUBQ1) • 
QNAME=QUE0E1 



PGM=. .. ,PARM='/QUEUE(SUBQ2) ' 

QNAME=QUEUE2 

QNAME=QUEUE3 



P.GM = . .. f PARM='/QUEUE (SUBQ3) ' 

QNAME=QUEUE2 

QNAME=QUEUE3 



Figure 165. Sample CJS Application (Part 1 of 2) 
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Notes: 

1. ILBOCJS must be an authorized program (via the OS/VS Authorized Program Facility) 

2. SYSTPIN designates the HCP gueue which will contain the messages sent by COBOL at the 
start and end of execution of a program which has been scheduled by the CJS. 

3. SYSOUT is used for error messages (via the COBOL DISPLAY statement) . 

4. SYSIN holds the CJS control statements, as described in "Using the CJS" above. 

5. The control statements in this example will do the following: 

• Every 10 seconds (of elapsed time), TCAM gueues QUEUE1, QUEUE2, and QUEUE3 will be 
polled for their message count. After 360 polling intervals (approximately one 
hour) , the CJS will terminate. 

• If QUEUE1 contains one or more messages, JOB1 will be started; QUEUE1 will not be 
polled again until an ENDED- message is received specifying QUEUE1. 

• If QUEUE2 contains four or more messages, JOB2 will be started. Since both QUEUE2 
and QUEUE3 have the same association code ("A") , neither will be polled again 
until an ENDED message is received specifying either QUEUE2 or QUEUF3. 

• If QUEDE2 contains less than four messages but QUEUE3 contains five or more 
messages, JOB3 will be started. Again, since both QUEUE2 and QUEUE3 have the same 
association code ("A") , neither will be polled again until an ENDED message is 
received specifying either QUEUE2 or QUEUE3. 

6. Since both J0B2 and JOB3 reference the same TCAM gueues (QUEUE2 and QUEUE3) , they 
must be prevented from being scheduled at the same time. This is accomplished by 
specifying the same association code for each (when either one is scheduled, both are 
removed from the polling seguence) . 

Figure 165. Sample CJS Application (Part 2 of 2) 

Summary of ANS Standard MCP Reguirements if communications job scheduling is not to 

be used, the SYSCJS TPEOCESS entry and its 
associated PCB need not be coded) . An MCP 
The MCP must contain provisions for only containing provisions for all ANS Standard 
those ANS Standard features that will be features is outlined in Figure 166. The 
used by COBOL application programs (e.g., following notes apply. 
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****************************************************** 

* HCP INITIALIZATION SECTION * 

****************************************************** 

INTRO CONTROL=PASSWD,... 

© ® 

ILBONBLQ^ ... 

• • • 

READY 



****************** ***** ****************** ************* 
* PROCESS CONTROL BLOCKS * 

***************** 4c ****************** ***^(* ************ 

PCB® 



APPLPCB1 

COBCHD1 

COBCJS 



PCB © 
PCB © 



******************** 

* TER 

******************** 

^ TTABLE 
COBOPTO^ OPTION 
COBOPT1® OPTION 
COBOPT2® OPTION 
COBOPT3®- OPTION 
CMDRDE ST® OPTION 



TERM1 



TERMINAL 



® 



I® 



QOEOEI^ T PROCESS© 
QUEUE2® TPROCESS® 

COBTPOU1® TPROCESS 
COBOPI N1 ^ TPROCESS 
CO BOPOU1© TPROCESS 



SYSCJS 



(D 



TPROCESS 



MH=APPLMH, DATE=YES>iV. . 
MH=COBCMDMH, BUFSIZE=80 
MH=C OBC JSMH , BOF SI ZE=5 1 

********************************** 

MINAL TABLE * 

********************************** 

... 

CL9 

FL1 

FL1 • 

XL11 

CL8 

OPDATA=(PASSWD/T1,0 f , X 

C3D6C2D6D7E3F37EA80008),... 
PCB= APPLPCB1,DAT£=YES, .. . ® 
PCB=APPLPCB1 ,DATE=YES, ® X 

OPDATA={PASSWD/Q2,, 1) , .. . 
PCB=APPLPCB1 ,.. . 

PCB=C0BCMD1, ... fa 

PCB=C0BCMD1,ALTDEST=C0B0PIN1 y X_ 
SECTERN=YES,OPDATA=(, , tt COBOPIS1 )® 
PCB=COBCJS,. .. 



****************************************************** 

* TYPICAL LINE GROUP MESSAGE HANDLER * 
****************************************************** 

LIN EH H STARTMH LC = ... 

* IN-MESSAGE SUBGROUPS 

ILBONBLT® 

• • • 

INMSG 
INEND 



OUT-MESSAGE SUBGROUPS 
OUTMSG 



OLD® 



HOLD 



5X»FF» , RELEASE, CONNECT= AND 



Figure 166. ANS Standard MCP Reguireaents (part 1 of 2) 
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OUTEND 



** * 41 41**4(41 * ******************************** ************ 
* TIPICAL COBOL APPLICATION MESSAGE HANDLER * 

****************************************************** 



APPLHH 



STAHTHH 

• • • 
INHDR 

FORWARD^ 

• • • 

' OOTHDR 



SETEOF 



® 



LL. ~ • • • 



DEST=POT 



OOTEND 
****************************************************** 

* ENABLE/DISABLE OPERATOR COMMAND MESSAGE HANDLER * 
****************************************************** 

COBCMDMH STAHTMH LC=OUT 



NONE 



DEST=CMDRDEST 



® 



• • • 

INHDR _^ 
CODE ® 

• • • 

FORWARD 

• • • 

INEND 

• • • 

OOTEND 



* ** ** * ** **** ** ** * *** ********* 4c 4c ** ***** **************** 

* COMMUNICATIONS JOB SCHEDULER (CJS) MESSAGE HANDLER * 

**************** 4c ******************************* ****** 

COBCJSMH STARTMH LC=OOT 

# • • 

OOTEND 



Figure 166. ANS Standard MCP Requirements (Part 2 of 2) 
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© 
© 



® 



This parameter must be coded if ENABLE 
or DISABLE statements are to be 
executed by COBOL programs. The value 
specified constitutes the global 
portion of the enable/disable key and 
may consist of from one to eight 
characters without embedded blank coaaa 
or slash ( W / H ) characters. 



This macro must be coded if DISABLE 
INPOT statements (without TERMINAL) are 
to be executed by COBOL programs. 

At least one PCB and its associated 
TPBOCESS entries must be defined for 
each COBOL application program that can 
be executed concurrently (a PCB can be 
associated with only one application at 
a time). These PCB»s and TPROCESS 
entries must specify DATE=YES. 

A PCB and two associated TPROCESS 
entries must be defined for each COBOL 
application program that can be 



© 

© 
© 



© 



executed concurrently and will execute 
ENABLE or DISABLE statements. 



If the Communications Job Scheduler 
utility (ILBOCJS) is to be executed, a 
PCB and associated TPROCESS entry must 
be coded. 

This option is required if local 
password protection is desired. 

This option is required if 
ENABLE/DISABLE INPUT TERMINAL 
statements are to be executed by COBOL 
programs. 

This option is required if 
ENABLE/DISABLE INPUT statements 
(without TERMINAL) are to be executed 
by COBOL programs. 

This option is required if 
characteristics are to be specified for 
symbolic destinations. 
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This option allows the same message 
handler to be used for all PCB*s 
required for ENABLE/DISABLE comaand 
processing (see item 4 ) - 

(Vj) The options for this entry specify: 

1. a local password value of 
"PASSWD/T1". 

2. the symbolic source represented by 
this entry lay be enabled and 
disabled (it is initially enabled) . 

3. the symbolic destination 
represented by this entry has the 
following characteristics: 

» vertical positioning is 
supported 

• forms feed is not supported 

• the destination has a fixed line 
size of eight bytes. 

• record delimiters are not to be 
inserted between segments. 

• a test should be made during 
each SEND to see if this 
destination is disabled. 

Q2) The absence of the OPDATA option for 
this entry implies: 

1. no local password protection 

2. the symbolic input queue 
represented by this entry may not 
be disabled. 

(n) The options for this entry specify: 

1. a local password value of 
"PASSWD/Q2" 

2- the symbolic input queue 

represented by this entry may be 
enabled and disabled (it is 
initially disabled) . 

@ DATE=YES must be coded for TPRGCESS 
entries representing symbolic input 
queues and their associated PCB's. 

@ This identifies C0B0PIN1 as the 

destination for TCAM reply messages to 
operator commands received through 
C0B0P0D1. 
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This macro must be coded if DISABLE 
INPUT TERMINAL statements are to be 
executed by COBOL programs for symbolic 
sources whose incoming messages are 
processed by this message handler. 

At least one HOLD macro must be coded 
in the MCP if DISABLE OUTPUT statements 
are to be executed by COBOL programs. 

This form of the FORWARD macro is 
required in message handlers that will 
process messages from COBOL programs. 



This macro may be used 
of group indicator {EG 
to the COBOL program f 
RECEIVE statement exec 
receipt of the end of 
(EMI) for the current 
RECEIVE statement must 
symbolic queue as that 
causinq the SETEOF mac 
and will have an accoi 
length of zero. 



to cause an end 

I) to be passed 

or the next 

uted after 

message indicator 

message. The 
specify the sam 
for the message 

ro to be executed 

panying text 
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This macro must be coded to allow TCAM 
to detect valid operator commands 
resulting from ENABLE/DISABLE 
statements executed by COBOL programs. 
A valid operator command will result if 
the key phrase of the ENABLE/DISABLE 
statement yields a valid global 
password. See item 16 for invalid 
operator commands. 



JCL FQRJTHE MCP 



This section names the parts of the MCP 
described earlier, explaining how to 
arrange them in relation to one another and 
how to assemble, link-edit, and execute a 
TCAM MCP. The five sections of an HCP 
include those previously discussed — an 
activation and deactivation section, a data 
set definition section, a terminal and line 
control area section, a message handler 
section — and an optional user routine 
section (that is, user subroutines called 
by a message handler, as well as exit 
routines referred to by the INTRO macro, by 
DCB macros, and by the STARTMH macro) . The 
only stipulation about ordering these 
sections is that the activation and 
deactivation section must come first. 



(16) The value of COBOPIN1 for the CMDRDEST 
option together with the FORWARD macro 
in the operator command lessage handler 
will send invalid operator commands 
back to the originating COBOL program 
(the program requires a response to 
each command issued) . 



ASSEMBLING, LINK-EDITING, AND EXECUTING AN 
MCP 



The assembly, link-edit, and execution 
steps of a TCAM MCP are similar to these 
steps for any other problem program running 
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under OS/VS. The job control statements 
given below for these three steps are 
guidelines only. 



Assemblin g an BCP 



A typical control card sequence for 
assembling a TCAM MCP is as follows: 

//ASSEMBLY JOB MSGLEVEL=1 
//STEP1 EXEC ASHFC 

//ASM.SYSIN DD * 

{BCP Source Deck} 



Li£irEaitjna „, a n .,, MC £ 



The following is a typical control card 
sequence for link-editing an MCP: 



//LINK EDIT 


JOB 


MSGLEVEL=1 


//STEP1 


EXEC 


PGH=IEWL,PARH='XHEF,LIST, 


// 




LET»,REGION=128K 


//SYSPRINT 


DD 


SYSOUT=ft 


//SYS0T1 


DD 


UNIT=SYSDA, 


// 




SPACE= {1024, (200,20) ) 


//SYSLBOD 


DD 


DSNAHE=SYS1„TCABLIB, 
DISP=QLD 


//SYSLIB 


DD 


DSNAME=SYS1.TELCMLIB, X 
DISP=SHR 


//SYSLIN 


DD 


* 



(BCP Object Module} 

NAME TCAMPROG(R) 

Mo te : In this example, the MCP load module 
is to be placed in a user-created private 
library called SYS1.TCAMLIB. 



Executing an MCP 



The TCAM MCP is normally executed as the 
highest-priority task in the 
highest- priority partition or region in the 
system. It may have an equal priority, but 
it should never be assigned a lower 
priority. A typical control card sequence 
for executing an MCP is the following: 



// DD 

// DD 

//QFILE DD 

//LOGFILE DD 
//SYSABEND DD 



Notes: 



UNIT=016 

UNIT=017 

DSNAME=MSGQ,DISP=OLD 

DSNAME=LOGF,DISP=OLD 

SYS0UT=A 



1. In this example, the BCP has two line 
group data sets, each containing three 
lines; no checkpoint facility is 
included. (For a discussion of the DD 
cards for a checkpoint data set, see 
the section "Defininq the Checkpoint 
Data Set.«) 



2. The QFILE DD statement is for a 

message queues data set residing on 
disk; QFILE is the name specified in 
the DDNAME= operand of the DCB macro 
for this data set, and MSGQ is the 
name of the data set specified by the 
DSNABE operand of the IEDQDATA DD 
statement for the IEDQXA utility used 
to preformat disk message queues data 
sets residinq on disk (see the section 
"Defining the Messaqe Queues Data 
Sets") . 



3. If the data set is not cataloqed, the 
UNIT= and V0LUME= operands must be 
included in the DD statement for the 
disk messaqe queues data set. 



4. The //LOGFILE DD card must be included 
if the LOG data set is to be used. 



Defininq t h e Checkpoint D ata Set: one DD 
stateaent that may or may not catalog the 
data set must be issued for the checkpoint 
data set. However, if it is not cataloqed, 
the user should allocate the data set by 
specif yinq DISP= {NEW, KEEP) as in the 
example and subsequent uses of the data set 
must contain the UNIT= and VOL=SER=keyword 
operands, qiven below. 



//CFILE DD DSNAME=CPDS,UNIT=2314, X 

// VOL=SER,DB197, X 

// SPACE=(TRK, (5)) , X 
// DISP= (NEW, KEEP) 



//EXECMCP 


JOB 


•EXECUTE BCP» f MSGLEVEL=1 


// 




PRTY=12 


//GO STEP 


EXEC 


PGfi=TCABPROG,REGION=100K 


//STEPLIB 


DD 


DSNAME=SYS1.TCAMLIB, 


// 




DISP=SHR 


//DD1050 


DD 


UNIT=025 


// 


DD 


ONIT=026 


// 


DD 


UNIT=027 


//DD2740 


DD 


UNIT=015 
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After a checkpoint data set is set up 
and the BCP has terminated normally, the 
programmer should replace the DD card 
described above with one of the following 
type: 

//CFILE DD DSNAME=CPDS,DISP=OLD, 

VOL=SER=DB197,UNIT=2314 

Defining Line Group Data Sets: The user 
must include in his job control statements 
at least one DD statement for each line 
group data set, but he has two options for 
handling these definitions. 



1 



2. 



3. 



//lni 

//LN2 



If a UNITNAME macro is issued for a 
line group at system generation time, 
then a single DD statement may be 
issued for this line group at HCP 
execution time- For example, a 
UNITNAME macro could be issued to 
define a group of lines as follows: 

UNITNAME UNIT=(040,041) 
NAHE=GROUPLTNE 

Shere the two numerals in the 
UNIT=operand parameter represent the 
hardware addresses of two lines in a 
line group. At execution time for the 
MCP, the following DD statement might 
be issued for this line group: 

//LNS DD UNIT=(GR0UPLINE,2) 

Where the line group data set would be 
made up of two lines defined by the 
UNITNAME macro. 

A DD statement may be issued for each 
line in a line group, as in the DD 
cards for line group DD1050 and line 
group DD2740 in the sample JCL 
statements given in section "Executing 
an MCP. " 

The following DD cards were used to 
execute the sample message control 
program shown in Figure 160. 

DD UNIT=040 (for the 1050 terminal) 
DD UNIT=041 (for the THX terminal) 



Defining the Message Queues Data .Sets: The 
number of message gueues data sets required 
for an MCP depends on the types of gueues, 
which, in turn, depend on the application. 
TCAM supports three types of data sets — a 
main storage data set, a reusable disk set, 
and a nonreusable disk data set. (For 
checklists governing specification of the 
three types of message queues data sets, 
see the publication OS/VS TCAM Programmer's 
Guide. 

TCAM expects the disk message queues 
(both reusable and nonreusable) to be 
totally preformatted. The COBOL user 



should engage the TCAM routine IEDQXA to 
perform this task prior to initially of a 
set of job control statements used to 
invoke this routine. 

Note: The value given in the KEYLEN 
parameter must be the same as that 
specified in the KEYLEN operand of the 
INTRO macro (see the section "Defining the 
Buffers") . 

//JOBNAME JOB user information 

//FORMATQ EXEC PGfi=IEDQXA 

//SYSPRINT DD SYS0UT=A 

//IEDQDATA DD 

// 

// 

// 

// 

/* 



DSN=MSGQ,DISP=(,CATLG) , X 

SPACE=(CYL, (5,5) ,,C0NTIG) X 

UNIT= (2314,1) , X 

VOL=SER=333333, X 
DCB=(,KEYLEN=100) 



WRITING. A TCAM-COMPATIBLE COBO L PR OGRAM 



Two of the chief processing applications 
for which COBOL programs can be written are 
inquiry processing and processing collected 
data. An inquiry-processing COBOL program 
receives messages from stations, processes 
the data, and then sends replies to the 
originating stations. Depending on the 
inquiry, the COBOL program may transmit 
either the information requested or a 
message stating that this information is 
unavailable and telling when it can be 
provided. The COBOL program that simply 
processes data collected by a message 
control program can either operate 
concurrently with the collection of data by 
the MCP or be loaded and initiated at a 
later time. 

The sample COBOL communication program 
TESTTP2 (shown in Figure 171 ) represents 
an application of processing data. This 
program accepts messages transmitted from a 
remote station, formats the message, and 
then transmits each complete message to the 
destination specified. The COBOL program 
TESTTP1 (shown in Figure 170) simulates 
terminal input data. The user can, 
therefore, test an installation-written 
COBOL TP program by running it with the 
sample MCP and TESTTP1. 



TESTING A COBOL TP PROGRAM 



Depending on the status of an 
installation's teleprocessing system, the 
user can code any one of three sets of JCL 
to run a teleprocessing job. A system that 
is fully operational has a message control 
program. with a user- designated message 
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handler for each type of teleprocessing 
situation expected, as well as remote 
terminal hook-ups. The user whose system 
is only partially developed or is still in 
the design stage may, nevertheless, wish to 
test COBOL teleprocessing programs using 
BSAM. 

Accordingly, the JCL shown in Figure 167 
is for a strictly BSAM situation (that is, 
for a communication program that is to be 
run without TCAM) ; the JCL shown in Figure 
168 is for a quasi-terminal situation (that 
is, with TCAM but without terminals) ; and 
the JCL shown in Figure 169 is for a 
communications job running with a remote 
terminal. For both the non-terminal and 
the quasi-terminal situation an input data 



set must be created. To run a COBOL 
communications program with a terminal 
hook-up, only the communications program 
itself is needed. 

To avoid unresolved external references 
from link edit when testing with BSAM and 
NORES, the programmer must point to the 
SYS1.TELCMLIB. (He may choose to override 
these unresolved references since they will 
not effect BSAM testing.) When testing 
with BSAM and RES, the programmer need not 
take any extra steps. 

When testing TCAM the user must provide 
a LKED.SYSLIB card for SYS 1.TELCMLIB when 
NORES is specified. A GO. STEPLIB card must 
be provided for SYS1.TELCMLIB. 



1//TESTTP1 

I// 

I//COB.SYSIN 

I 

I 
,/* 

J//GO.TSTTP 

I// 

I//GO.C0BTPO0T 

»// 
J//TESTTP2 

I// 
I//COB.SYSIN 

I 

I 

j/* 

I//G0.Q1 

I//GO.COBTPO0T 

!// 

| //DOM PIT 

«// 

I//SYSLIB 

I// 

| //SYS PRINT 

J//SYSIN 

I 

I/* 



JOB user information 

EXEC COBUCLG 

DD * 

{Source deck for TESTTP1 program (Figure 163)} 

DD» UNIT=2400,LABEL=(#NL) , V0L=SE8=NI1 95,DCB= (LRECL=50 , BLKSIZE=50, 

RECFM=F,DEN=2) 
DD* ONIT=2314,VOL=SER=231400,DSN=SP1,DISP=(NE«,PASS) , 

SPACE=(CYL, (1,2)) 
JOB user- information 
EXEC COBUCLG 
DD * 



{Source deck for TESTTP2 program (Figure 166) } 

DD3 DSN=&P1,VOL=SER=231400,ONIT=2 314,DISP=(OLD,PASS) 
DD* DSN=&P2,VOL=SER=231400,UNIT=2314,DISP=(NEW,PASS) , 

SPACE=(CYL, (1,2)) 
JOB user-information 
EXECS PGM=xMASPZAP 
DD DSNAME=data set to be printed, UNIT=231 4, V0L=SER=23 1400, 

DISP=OLD,DCB=DSORG=PS 
DD SYSOUT=A 
DD * 
ABSDUMP ALL 



I- 

! 

I 

J1. Input sequential file with records of 50 characters each (BSAM JCL). 

I 

|2. Output data set that simulates sending messages to a terminal named •Pi*. 

I 

| 3. Input data set that simulates reading messages from a terminal named *P1». 

I 

J4. Output data set that simulates sending messages to a terminal named *P2*. 

I 

| 5. This job prints out the records in the simulated data set. For further 

1 information, see the publication OS/VS Service Aids . 

I 

1 6. For OS/VS1: HMASPZAP; for OS/VS2: AHJLSPZAP. 

I ; , 

Figure 167. Sample JCL for Testing a Communication Job Sithout TCAM. 
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1//TESTTP1 JOB user information 

I// EXEC COBOCLG 

| //COB. SYS IN DD * 

i 

J {Source deck for TESTTP1 program (Figure 165)} 

1/* 

I//GO.STEPLIB DD DSN=SYS1 .TELCMLIB,DISP=SHR 

I//GO-TSTTP DD» aNIT=2400,LABEL= (, NL) , VOL=SER=NI 195,DCB= (LRECL=50 , BLKSIZE=50, 

I// RECFM=F,DEN=2) 

J //GO. CO BT POUT DD* QNAME=P0UT1 

1//TESTTP2 JOB user information 

|// EXEC COBOCLG 

I//COB.SYSIN DD * 

1 

f {Source deck for TESTTP2 program (Figure 166)} 

I/* 

I//GO. STEPLIB DD DS N=SYS 1 . TELCMLIB, DISP=SHR 

J //GO. Q1 DD3 QNAME=P1 

J//GO.C0BTPO0T DD* QNAME=P0UT1 

I//DDMPIT JOB user information 

J// EXEC IEDQXC 

1//DISQ01 DDS DSN=MSGQ,V0L=SER=DB197,UNIT=23 14,DISP=SHR 

J//SYSPRINT DD SYSOUT=A 

I/* 

I 



1 Notes; 

i 

|1. Input seguential file with records of 50 characters each. (This is the same JCL as 

| in BSAM.) 

I 

J 2. Output is sent to an MCP message gueue named «Pl f , which is defined for processing 

| by a COBOL program. 

i 

J 3. Input is received from the MCP message gueue named *P1». 

1 

1 1*. Output is sent to an MCP message gueue named ' P2', which is defined for processing 

| by a COBOL program. 

I 

J 5. This job prints out records in the MSGQ gueue. For further information, see the 

I publication Qg/VS TCAM Programmer s G ui de . 

• , 

Figure 168. Sample JCL for Running a Communication Job in a Quasi-Terminal Environment. 



I//TESTTP2 JOB user information 

|// EXEC COBUCLG 

I //COB. SYS IN DD * 

I {Source deck for TESTTP2 program (Figure 154)} 

!/* 

J//GO.STEPLIB DD DSN=SYS1 .TELCMLIB,DISP=SHR 

J//GO.Q1 DD* QNAME=P1 

I//GO.COBTPOUT DD* QNAME=P0UT1 



I Notes: 

! 

11. The input is received from the MCP message gueue *P1*. 
I 

12. The output is sent to an MCP message gueue defined for a terminal. 

i 

Figure 169. Sample JCL for Running a Communication Job with a Remote Terminal 
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COMMUNICATING BETHEEN A COBOL PROGRAM AND 
THE HCP 



The TCAM message control program routes 
messages between a COBOL teleprocessing 
program and remote stations. Because the 
MCP performs the input/output operations 
necessary for the COBOL teleprocessing 
program, the user must establish an 
interface between these two programs by 
doing the following: 

• Defining the interface 

• Activating the interface 

• Transferring messages between the COBOL 
program and the MCP 

• Deactivating the interface 

In each of the sections that follow, both 
COBOL statements and TCAM macros, as well 
as their relationship, are described as 
appropriate. The encircled numerals in 
this discussion refer to the sections 
similarly labeled in the sample COBOL 
teleprocessing program TESTTP2 shown in 
Figure 171. 



Defining the Interface 



The Communication Section in the COBOL 
program and the PCB and TPROCESS macros in 
the message control program set up the 
interface between the two programs. 

Asso cia ting COBOL Symbol ic Queue Ma tes, with 
T.CAM n queues: COBOL associates the symbolic 
gueue names specified in an input CD with 
TCAM queues according to the following 
algorithm: 

1. If a queue structure definition 
(created by the queue structure 
utility, ILBOQSU) exists for the 
SYMBOLIC QOEUE name in the CD, the 
SYMBOLIC SUB-QUEUE- 1 through SYMBOLIC 
SUB-QUEUE-3 names are used to derive a 
VS JCL ddname value from the 
definition. 

2. If a queue structure definition does 
not exist for the SYMBOLIC QUEUE name 
in the CD and SYMBOLIC SUB-QUEUE- 1 
through SYMBOLIC SUB-QUEUE-3 names 
contain spaces, the first eight 
characters of the SYMBOLIC QUEUE name 
are used as the ddname. 

3. If neither of the above steps yields a 
ddname, the queue is unknown (CD 
STATUS KEY = »20») . 



Any ddname produced by the algorithm 
above must have a corresponding DD card of 
the following format: 

//ddname DD QNAME=procname 

[ ,DCB=BLKSIZE=n] 

where procname is the name of the TCAM 
TPROCESS Terminal Table entry with which 
the input queue is to be associated, and n 
is the blocksize of the TCAM buffer used by 
COBOL., The BLKSIZE parameter is only 
effective for the first input or output 
queue opened (COBOL uses a single buffer 
for all TCAM queues) and has a default 
value of 200. 



Identif yin g_ the ..Queue Structure Definition 
Data Set: The queue structure definitions 
created by the queue structure utility, 
ILBOQSU, are made available to COBOL by 
specifying the following DD card: 

//COBTPQD DD data set information 



Associating COBOL, Symbolic .Source Names 
with TCAM Sources: The first eight 
characters of each symbolic source name 
used by COBOL must be the name of a TCAM 
TERMINAL or TPROCESS Terminal Table entry 
that can act as a source for incoming 
messages. No special DD cards are 
required. 

Associating C QBOL Symbolic Destination 
Na mes wit h TCAM Destinati ons: The first 
eight characters of each symbolic 
destination name used by COBOL must be the 
name of a TCAM TERMINAL or TPROCESS 
Terminal Table entry that can act as a 
destination for outgoing messages. In 
addition, the following DD card is 
required: 

//COBTPOUT DD QNAME=procname 

£ ,DCB-BLKSIZE=N] 

WHERE PROCNAME IS THE NAME OF A TCAM 
TPROCESS Terminal Table entry that can act 
as a source for incoming messages and n is 
the blocksize of the TCAM buffer used by 
COBOL. The BLKSIZE parameter is only 
effective for the first input or output 
queue opened (COBOL uses a single buffer 
for all TCAM queues) ; it has a default 
value of 200. 

This DD card is also required if a CD 
FOR INITIAL INPUT is defined in the COBOL 
program and the program is scheduled by the 
CJS. 

Specif ying, the ESABLE/DISA8LE Command 
Interface: If iNABLl or DISABLE statements 
are to be executed by the COBOL program, 
the following ^>Q cards are required: 
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//COBOPGOT DD QNAME=procname-1 procname-2 is the name of a TCAH TPHOCESS 

//COBOPIN DD QNAME=procname~2 Terminal Table entry to »hich operator 

command reply messages are to be sent (see 

where procname-1 is the name of a TCAM "ENABLE/DISABLE: Operator Command 

TPSOCESS Terminal Table entry defined as a Interface") . 

secondary operator control station, and 
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001010 IDENTIFICATION DIVISION. 

001020 PROGRAM-ID. 

001030 TESTTP1. 

001080 DATE-COMPILED. MAY 1, 1974 

001100 REMARKS. THE SAMPLE COBOL TELEPROCESSING PROGRAM THAT 

FOLLOWS SERVES AS A SIMPLE ILLUSTRATION OF THE COBOL TELE- 
PROCESSING FEATURE. THIS PROGRAM READS IN A FILE OF 50- 
CHARACTER MESSAGES, TRANSMITTING THEM ONE BY ONE TO THE 
SPECIFIED DESTINATION. 

001160 

001170 ENVIRONMENT DIVISION. 

001180 INPUT-OUTPUT SECTION. 

001190 FILE-CONTROL. 

001200 SELECT MASTER-FILE 

001210 ASSIGN TO UT-2400-S-TSTTP. 

002010 DATA DIVISION. 

002020 FILE SECTION. 

002030 FD MASTER- FILE 

002040 RECORDING MODE IS F 

002050 LABEL RECORDS ARE STANDARD 

002060 DATA RECORD IS SECORD1. 

002070 01 RECORD1 PIC X (50) . 

003010 WORKING -STORAGE SECTION. 

003110 

003120 01 IDENT-SEND. 

003130 02 I-SEND PIC X{50). 

* SET UP A WORK AREA OF 50 CHARACTERS 
003150 

* THE COMMUNICATION SECTION MUST BE SPECIFIED IN A COBOL PROGRAM 

* THAT IS TO UTILIZE THE COBOL TELEPROCESSING FEATURE. THE 

* COMMUNICATION DESCRIPTION (CD) ENTRIES THAT APPEAR IN THIS 

* GROUP OF SOURCE STATEMENTS ESTABLISH THE INTERFACE BET8EEN THE 

* COBOL OBJECT PROGRAM AND THE MESSAGE CONTROL PROGRAM (MCP) . 
004010 COMMUNICATION SECTION. 

004120 CD CDNAHE-OUT FOR OUTPUT 
004130 TEXT LENGTH IS TEXTLNTH-OUT 

* SPECIFY LENGTH OF OUTPUT MESSAGE. 
004140 STATUS KEY IS STATKY-OUT 

* PROVIDE INFOBMATION ON MESSAGE STATUS. 
004150 ERROR KEY IS ERRKY 

* PROVIDE ERROR INFORMATION. 
004160 SYMBOLIC DESTINATION IS SYMDSS. 

* SPECIFY OUTPUT QUEUE. 
004170 

005010 PROCEDURE DIVISION. 

005020 START-JOB. 

005030 DISPLAY 'BEGIN TESTTP1 • . 

* START THE COBOL TELEPROCESSING PROGRAM. 
005040 OPEN INPUT MASTER-FILE. 

* OPEN THE INPUT FILE. 
005045 READ-ROUTINE. 

005050 READ MASTEB-FILE INTO IDENT-SEND 

005060 AT END GO TO END-ROUTINE. 

* PLACE INPUT RECORDS IN A WORK AREA UNTIL END OF FILE IS 

* REACHED. 
006010 SEND-ROUTINE1. 

006020 MOVE f P1» TO SYMDES. 

* SET UP OUTPUT DESTINATION. 
006040 MOVE 50 TO TEXTLNTH-OUT. 

* IDENTIFY MESSAGE LENGTH AS 50. 

006060 SEND CDNAME-OUT FROM IDENT-SEND WITH EMI. 

* TRANSMIT A COMPLETE MESSAGE. 

006070 PERFORM CHECK-SEND THRU CHECK-EXIT. 
006080 GO TO READ-ROUTINE. 

Figure 170. Creating a TCAM Data Set for Testing without Terminals (Part 1 of 2) 
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* EXECUTE USES-WRITTEN CODE FOB CHECKING ON THE SUCCESSFUL 

* COMPLETION OF HESS AGE TRANSMISSION. IF END OF FILE IS 

* REACHED, GO TO END-OF-JOB ROUTINE. OTHERWISE, GET THE NEXT 

* RECORD. 
008010 CHECK-SEND. 
008020* 

008021* 
008022* 

008030* USEE CHECKING ROUTINE FOR DETERMINING THE 

008040* SUCCESSFUL COMPLETION OF THE SEND. 
008050* 
008160 

008170 CHECK- EXIT. 

008180 EXIT. 
**008180* 
008190 

011110 END-ROUTINE. 

011111 CLOSE MASTER-FILE. 

* CLOSE THE INPUT FILE. 

011150 DISPLAY 'SUCCESSFUL END OF TESTTP1*. 

* TERMINATE THE PROGRAM. 
011160 STOP BUN. 

Figure 170. Creating a TCAM Data Set for Testing without Terminals (Part 2 of 2) 
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001010 IDENTIFICATION DIVISION. 

001020 PROGRAM-ID. 

001030 TESTTP2. 

001080 DATE-COMPILED. BAY 1, 1974 

001100 REMARKS- THE SAMPLE COBOL TELEPROCESSING PROGRAM THAT 

FOLLOWS SERVES AS A SIMPLE ILLUSTRATION OF THE COBOL TELE- 
PROCESSING FEATURE. THIS PROGRAM SETS UP A DESTINATION 
FOR INCOMING MESSAGES, AND THEN READS THEM, ONE BY ONE, 
INTO A WORK AREA. THE PROGRAM BUILDS 50-CHARACTER MESSAGES 
AND SENDS THEM TO THE MCP KITH THE END-OF-MESS AGE (EMI) 
INDICATOR. WHEN ALL THE INCOMING MESSAGES HAVE BEEN PRO- 
CESSED, THE MESSAGE 'SUCCESSFUL END OF TESTTP2 * IS PRINTED 
ON THE CONSOLE, AND THE PROGRAM IS TERMINATED. 

001120 

001130 

001170 ENVIRONMENT DIVISION. 

001180 CONFIGURATION SECTION. 

001190 INPUT-OUTPUT SECTION. 

001200 

002010 DATA DIVISION. 

WORKING-STORAGE SECTION. 

003110 

003120 01 IDENT-SEND. 

003130 02 I-SEND PIC X(50). 

003160 01 IDENT-REC. 

003170 02 I-REC PIC X(50). 

03190 

* THE COMMUNICATION SECTION MUST BE SPECIFIED IN A COBOL PROGRAM 

* THAT IS TO UTILIZE THE COBOL TELEPROCESSING FEATURE. THE 

* COMMUNICATION DESCRIPTION (CD) ENTRIES THAT APPEAR IN THIS 

* GROUP OF SOURCE STATEMENTS ESTABLISH THE INTERFACE BETWEEN THE 

* COBOL OBJECT PROGRAM AND THE MESSAGE CONTROL PROGRAM (MCP). 
COMMUNICATION SECTION. 

04120 CD CDNAME-OUT FOR OUTPUT 
004130 TEXT LENGTH IS TEXTLNTH-OUT 

* SPECIFY LENGTH OF OUTPUT MESSAGE. 
004140 STATUS KEY IS STATKY-OUT 

* PROVIDE INFORMATION ON OUTPUT MESSAGE STATUS. 
004150 ERROR KEY IS ERRKY 

* PROVIDE ERROR INFORMATION. 

0416 SYMBOLIC DESTINATION IS SYMDES. 

* SPECIFY OUTPUT QUEUE. 
004170 

**004020 CD CDNAME-IN FOR INPUT 
004030 SYMBOLIC QUEUE IS SYMQ 

* IDENTIFY INPUT MESSAGE QUEUE. 
004040 MESSAGE DATE IS MSGDATE 
004050 MESSAGE TIME IS MSGTIME 

* PROVIDE DATE AND TIME OF RECEIPT OF MESSAGE. 
004060 SYMBOLIC SOURCE IS SYHSOURCE 

* IDENTIFY THE MESSAGE SOURCE. 
004070 TEXT LENGTH IS TEXTLNTH-IN 

* SPECIFY THE EXPECTED LENGTH OF INPUT MESSAGE. 
004080 END KEY IS ENDKY 

* PROVIDE CODE FOR ACTIVATING END-OF-JOB ROUTINE. 
** FOR A RECEIVE MESSAGE: 

* A CODE OF 3 INDICATES END OF GROUP (EGI) . 

* A CODE OF 2 INDICATES END OF MESSAGE (EMI). 

* A CODE OF INDICATES RECEIPT OF LESS THAN A MESSAGE. 
** FOR A RECEIVE SEGMENT: 

* A CODE OF 3 INDICATES END OF GROUP (EGI) . 

* A CODE OF 2 INDICATES END OF MESSAGE (EMI). 

* A CODE OF 1 INDICATES END OF SEGMENT (ESI) 

* A CODE OF INDICATES RECEIPT OF LESS THAN A SEGMENT. 

Figure 171. A COBOL Program That Processes TCAM Messages (Part 1 of 2) 
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** HIERARCHY ~ 0, ESI, EMI, ETI-WHEN MORE THAN ONE CONCURRENTLY- 

* HIGH LEVEL APPEARS. 
004090 STATUS KEY IS STATKY-IN 

PROVIDE INFORMATION ON INPUT MESSAGE STATUS. 
004100 MESSAGE COUNT IS MCOUNT. 

* SPECIFY MESSAGE COUNT FOR INPUT QUEUE. 
04110 

**002100 

©PROCEDURE DIVISION. 
DISPLAY 'BEGIN TESTTP2'. 
RE CV -DAT A. 
009040 MOVE 'Q1' TO SYMQ. 

* SET UP INPUT DESTINATION. 
009050 RECEIVE CDNAME-IN MESSAGE INTO IDENT-REC 
009055 NO DATA GO TO END-ROUTINE. 

* ACCEPT INPUT MESSAGES, ONE BY ONE, AS ON A SEQUENTIAL FILE. 

* WHEN ALL MESSAGES HAVE BEEN PROCESSED, INVOKE END-OF-JOB 

* ROUTINE. 
009060 CHECK-RECEIVE. 
009070* 

009080* USER CHECKING ROUTINE FOR DETERMINING THE 
009090* SUCCESSFUL COMPLETION OF THE RECEIVE. 
009100* 

009110 PROCESS-DATA. 
009120* 

009130* USER ROUTINE TO BUILD MESSAGE TO BE SENT. 
009140* 
**006010 SEND-ROUTINE1. 

006020 MOVE 'P2' TO SYMDES. 

* SET UP OUTPUT DESTINATION. 

* NOTE: FOR THE NON-TERMINAL AND PARTIAL TERMINAL SITUATIONS, 

* 'P2' SHOULD BE SPECIFIED AS THE SYMBOLIC DESTINATION. FOR 

* A COBOL PROGRAM RUNNING WITH TERMINALS, 'T1' SHOULD BE 

* SPECIFIED. 

006040 MOVE 50 TO TEXTLNTH-OUT. 

®* SPECIFY LENGTH OF OUTPUT MESSAGES. 
006060 SEND CDNAME-OUT FROM IDENT-SEND WITH EMI. 

* TRANSMIT FORMATTED MESSAGE, WITH THE CODE FOR A COMPLETE 

* MESSAGE. 

006070 PERFORM CHECK-SEND THRU CHECK-EXIT. 

* INVOKE USER-WRITTEN ROUTINE FOR CHECKING MESSAGE TRANSMISSION. 

* ACCEPT THE NEXT MESSAGE FROM THE INPUT QUEUE. 
006090 GO TO RECV-DATA. 

007120 

008010 CHECK-SEND. 

008020* 

008030* USER CHECKING ROUTINE FOP DETERMINING THE 

008040* SUCCESSFUL COMPLETION OF THE SEND. 

008050* 

008170 CHFCK-EXIT. 

008180 EXIT. 

008190 

011110 END-ROUTINE. 
^^ 011150 DISPLAY 'SUCCESSFUL END OF TESTTP2 • . 
(5) 011160 STOP RUN. 

Figure 171. A COBOL Program That Processes TCAM Messages (Part 2 of 2) 
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Defi ning Process Contro l B lo cks: In the Notes.: 

MCP the user Bust also code a process 

control block (PCB) for each active 

application program running with the MCP. 

The PCB macro specifies the name of the PCB 

process control block generated by the 

macro. The process control block is 

referred to in the TPROCESS macro (see 

"Defining the MCP Data Sets and Process 

Control Blocks"). 



* A ctivating the Interface 



The COBOL programmer coding a program 
for a teleprocessing application 
initializes »ork areas, (T) , and activates 
the COBOL program as for any other OS/VS 
application. In this application, the job 
begins with the use of the DISPLAY 
statement "BEGIN TESTTP2," (2) . The COBOL 
programmer need not be concerned with how 
the interface is activated. The interface 
is activated when the first RECEIVE or SEND 
statement is issued. 



Tran sferr i ng Messages betw een the COBOL 
Program and the MCP 



For an additional example of the format 
of the RECEIVE statement and the SEND 
statement, see the section "Procedure 
Division" in the chapter on 
"Programming Technigues". 

The amount of data transferred from the 
MCP to a COBOL program by a single 
RECEIVE statement, or transferred from 
an application program to the MCP by a 
single SEND statement, is called a 
"work unit". Each work unit is 
processed in a user-designated work 
area in the COBOL program. 



Deactivating the Inter face 



As in all American National Standard 
COBOL programs, the teleprocessing 
application user returns control to the 
system by issuing a STOP RUN statement. 



<S> 



TCAM enables the application programmer 
to obtain messages from the MCP and to 
return response messages to the MCP. 
Specifically, the COBOL programmer can use 
either the RECEIVE statement or the SEND 
statement to transfer data between the MCP 
and the COBOL program, depending on the 
direction of the flow of data. 

T he RECEI VE Statement: This COBOL source 
statement causes transmission of message 
data from an input queue to a 
user-specified work area in the COBOL 
program. In the sample COBOL 
teleprocessing program shown in Figure 166, 
the RECEIVE statement, (3) , transfers data 
from the input queue referred to by SYMQ to 
a work area. The COBOL sentence before the 
RECEIVE statement is "MOVE «Q1« TO SYMQ," 
so the data is received from Q1. 

The SEND Statement : The COBOL source 
statement causes data from the COBOL 
program to be placed in an output queue for 1. 
subsequent transmission. Accordingly, when 
the outgoing message has been formatted, 
the sample SEND statement, (5) , transmits 
it to the output destination referred to by 
SYMDES. The end~of- mess age indicator (EMI) 
signals a complete message. The first 
sentence in the paragraph labeled 
"SE8D-R0UTINE1" is "MOVE f P2« TO SYMDES," 
so the data is sent to P2. 



Note: So that the COBOL program can give 
control to the STOP RON statement, the MCP 
writer should include in the message header 
a special code for the COBOL program. 
Although the sample MCP (Figure 16 0) has an 
action code field which includes such a 
code in the section of comments immediately 
preceding the MH1050 message handler, 13 , 
Figure 166 gives control to the STOP RON 
statement only when there is no more data. 
This technique is acceptable for a COBOL 
program that receives a fixed amount of 
data, i.e., a program that is not 
continually looping waiting for data. 
Alternatively, the MCP macro SETEOF can be 
used to cause an EGI, which could be used 
as an indication that STOP RUN processing 
should be initiated. 



Additional Interface considerations 



The information that follows is a 
summary of miscellaneous recommendations 
and/or restrictions that apply to the 
communication between the message control 
program and the COBOL application program. 



The parameter DATE=YES must be coded 
in all input TPROCESS entries whose 
destination is a COBOL program and the 
parameter is also required in the PCB 
macro referenced by the TPROCESS 
macro. Inclusion of this parameter 
causes the date and time of message 
entry to be placed in the MESSAGE DATE 
and MESSAGE TIME clauses of the input 
CD (see "Communication section" in the 
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2. 



3. 



chapter entitled "Programming 
Techniques") . 

The 8ECDEL= parameter must be coded in 
the TPROCESS macro of the MCP if the 
COBOL programmer is to accept (via the 
RECEIVE statement) or transmit (via 
the SEND statement) data in SEGMENT 
mode. The user nay either include in 
the incoming message the delimiter 
specified in this parameter or insert 
it via a MSGEDIT macro (see the 
section "Designing the Message 
Handler" in this chapter). 



The INITIATE macro 
message handler for 
destination is a CO 
macro would cause t 
segments of a taessa 
queue before receiv 
message. American 
COBOL, on the other 
a complete message 



cannot be used in a 

messages whose 
BOL program. This 
he MCP to transmit 
ge to a destination 
ing the complete 
National standard 

hand, assumes that 
has been enqueued. 



6. 



setting of the ESI (end of segment) 
indicator if end of segment is 
reached. When end of segment is also 
end of message, an end key of 2 
indicating EMI is given. If the last 
two characters in the message are an 
end segment indicator and the end of 
message character, the user rill 
receive the ESI indication first. 
Another RECEIVE sill be necessary to 
receive the EMI indication. The 
RECEIVE from the EMI indication will 
set the TEXT LENGTH field of the input 
CD to zeros. 

For a message transmitted from a COBOL 
program to the location specified in 
the SYMBOLIC DESTINATION clause of an 
output CD, the FORWARD macro in the 
inheader subgroup of the MH for the 
COBOL program must specify DEST=PuT-as 
its operand. 



5. 



American National Standard COBOL 
removes the last character of a 
message if it is X'37 1 (which is the 
EBCDIC representation for the EOT 
character). This is the last 
character of a message from a terminal 
that has been translated in the MH of 
the MCP via the CODE macro, or that is 
not processed in conversational mode 
(which would have been specified by 
coding CONV=YES in the STABTMH macro) . 

An execution of the RECEIVE statement 
with the SEGMENT option results in the 



DSIHG TCAM SERVICE FACILITIES 



TCAM allows for a variety of services in 
support of a COBOL communication system. 
Some of these services are provided 
automatically; others the user must 
specify. Some of the TCAM services are the 
following: operator control, error 
recovery, checkpoint/restart, message 
logging, debugging aids, and an on-line 
test feature. All of these TCAM aids are 
discussed in the publication OS/VS TCAM 
Progra miner's, Guide . 
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MACHINE CONSIDERATIONS 



This chapter contains information 
concerning system requirements for the 
COBOL compiler, execution time, and the 
sort/merge feature. Additional information 
for use in estimating the main and 
auxiliary storage requirements is contained 
in the publication O S/V S COB OL Compiler an d 
Libr ary Installation Reference Materia l. 



MINIMUM MACHINE REQUIREMENTS 



The basic system requirements for use of 
the COBOL compiler are: 

• A System/370 model, with the standard 
and decimal instruction sets. The 
floating-point instruction set is 
required if floating-point data items 
and fractional exponents are used in 
the program. 

• Compiler Work Files — Six utility data 
sets named SYSUT1, SYSUT2, S0SYT3, 
SYS0T4, SYSUT5 (if the SYMDHP option is 
specified) and SYSUT6 (if LVL option is 
specified). At least one mass storage 
device , such as an IBM 3340 Direct 
Access Storage Facility Storage Drive, 
for residence of the operating system 
and SYSUT1. Both the operating system 
and SUSYT1 may reside on the same 
volume. The data sets SYS0T2, SYSUT3, 
SYSUT4, SYSUT5 and SYSUT6 can reside on 
tape or on mass storage. If they 
reside on tape, there must be a tape 
volume for each data set. If they 
reside on mass storage, there must be 
enough space on the volume to 
accommodate the data sets. 

• A device, such as the 3215 
Printer-Keyboard, for direct operator 
communication. 

• A device, such as a card reader or a 
tape unit, for the job input stream. 

• A printer or tape unit for the system 
output file. 



In most instances, the compiler will 
perform adequately with a 128K SIZE. 
However, compiler efficiency usually 
increases with a larger SIZE allocation. 
This is because of the availability of 
larger buffers for compiler files, and/or 
the reduction or elimination of dictionary 
spills. Also, certain situations may make 
a larger SIZE specification not only 
preferable but necessary; for example: 

• A large or complex source program. 
Compiling such a program reguires more 
space for compiler internal tables. 

• User-specified compiler SYSOT data set 
blocking factors that reguire large 
buffers (see Appendix D). 

On the other hand, while a generous SIZE 
allocation is usually advantageous, it must 
not exceed the amount of contiguous problem 
program storage available to the compiler 
in the region or partition. The following 
calculation can be used to obtain a rough 
approximation of the maximum SIZE 
allocation possible: 



SIZE = REGION 



X - N 



where 



X = total sizes of any other programs 
in the region (zero if the 
compiler is alone) 



N = 6K for VS2 

6K + (SWA if used) 
overhead) for VS1 



4- (any job-step 



The variable N accounts for storage used or 
fragmentation caused by the operating 
system. Under VS1, if the compiler is not 
the first job step, earlier job steps may 
haye caused additional storage to be used 
or fragmented by the system, and this 
storage may not be freed until job 
termination. (This indefinite loss is 
noted in the above calculation as 'job-step 
overhead. * ) 



COMPILER SIZE REQUIREMENTS 



At least 128K (131,072) bytes should be 
allocated in the SIZE option of the EXEC 
job control card that requests execution of 
the compiler. If less than this is 
specified, the system assumes the default 
value of 128K. 



QS. /YS2 and the Region Param eter 



COMPILATION: If the compiler is being 
executed under OS/VS2, the REGION 
parameter, specified as 128K bytes in the 
COBUC anc. COBUCLG cataloged procedures, 
becomes significant (see the section "Using 
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the Cataloged Procedures") . If the 
programmer wishes to override this value, 
he can specify a region size in either the 
JOB statement or in the EXEC statement of 
the compiler. The size specified should 
not be less than the value of SIZE in the 
PARM field of the EXEC statement. 

The following examples illustrate both 
the default and the override cases: 



Exa m ple 1 

//J0B1 
//STEP1 



JOB 1234, J. SMITH 
EXEC COBUC 



In this example, the programmer 
accepts the REGION default value of 
128K specified in the COBUC cataloged 
procedure. 



//J0B2 

//STEP1 

// 



JOB 1234,J.SHITH 
EXEC C0BUCLG,REGI0N=196K, 
PARM.COB=*SIZE=196K» 



In this example, the REGION default 
value is overridden. 



EXECPTIpN: Priori 
that the REGION pa 
execution of objec 
programmer is will 
region size. The 
established in the 
The region size ne 
the object program 
following values: 



ty schedulers require 
rameter be specified for 
t programs, unless the 
ing to accept default 
default value is 

input reader procedure, 
eded for the execution of 

is the sum of the 



1. The size of the object module after it 
has been link-edited with all of the 
necessary object time subroutines. 

2. The size of the inpiit /output buffers 
being used, multiplied by the blocking 
factor (physical sequential files are 
double buffered if no blocking factor 
is specified) . 

3. The size of the data management 
routines and control blocks that are 
used {see the publication S/ VS 2 
Storage Estimates! . 

4. Any GETHAIN macro instruction executed 
for USE LABELS, etc. 

5. An additional 6K bytes. 

6. If the Sort/Her ge feature is used, 
15,360 bytes plus any additional main 



storage assigned via the 
SORT-CORE-SIZE special register. 



Intermediate Data Sets Under 0S/VS2, 
Release 1 



SYS IN and SYSOUT data resides in 
intermediate direct-access data sets. 
These data sets are used by the system to 
temporarily hold all of the job*s input and 
output data. For SYSOUT, the programmer 
must use override statements as described 
in "Using the Cataloged Procedures." 



Output is placed in 
intermediate data set. 
written out until the c 
job, the programmer mus 
SYSOUT data set is larg 
of the possible output 
The SPACE parameter of 
specified for SYSOUT wi 
default value. If the 
determines that his out 
default yalue, he can d 
two things: 



the SYSOUT 

Since nothing is 
ompletion of the 
t make sure that the 
e enough to hold all 
data of his program, 
the DD statement is 
th a specified 
programmer 
put will exceed the 
o either or both of 



1. specify blocking of his data set with 
the DCB parameter of an override DD 
statement 

2. override the compilation step of a 
compiled procedure by specifying the 
SPACE parameter. An example of a 
statement that can be used is: 



//COB. SY SPRINT DD 
// UNIT=SISSQ 



SPACE=<121, (500,50)) , 



Note: If the TRK or CYL subparameters of 
the SPACE parameter are used, the 
programmer should be aware that requests 
will differ depending upon the mass storage 
device used (2314, 3330 ..., etc.). To 
avoid this consideration, the average 
record-length subparameter can be used. 



EXECUTION TIME CONSIDERATIONS 

The amount of main storage must be 
sufficient to accommodate at least: 

• The control program 

• Data management support 

• The load module to be executed 

When the OPTIHIZE option is specified, 
the number of procedure blocks in the 
program cannot exceed 255. A procedure 
block is approximately 4096 bytes of 
Procedure Division code. 
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COBOL programs compiled with any of the 
symbolic debugging options (STATE, FLOW, 
SIMDMP) have execution time requirements 
that differ from those of similar programs 
compiled without these options. If the 
SIMDMP option is in effect 9 the data set it 
required at compile time (SYSUT5) must be 
present at execution time. 

The total space required for object-time 
debugging should be calculated as follows: 



where 



s = s + 

TS DBG 



S + 
FLW 



SYMDMP 



STN 



STN 



SYMDMP 



+ rs -I 

L FLW J 

♦ rs I 

|_ FLW J 



= the number of verbs in the 
COBOL program <a number that 
is approximately equal to the 
number of statements in the 
program) 



S =(11250 ♦ S +S ) bytes 
SYMDMP TABLES DM 



| where 
1 

IS 

I TABLES 

J 
IS 

| DM = 



= the size of tables for SYMDMP 



the size of data management 
required for SYMDMP 



where: 

S 
TS 

S 
DBG 



FLW 



STN 



= the total space 



the space allocated once and 
only once for a run containing 
any object-time debugging 
options 



the space required for the FL08 
option 



the space required for the 
STATE option 



SYMDMP = the space required for the 
SYMDMP option 



• S = 3700 bytes 

DBG 

• S =(1208 ♦ 4*nn + 10*P) bytes 

FLW 

where 

nn = the number specified in the 

FLOW=nn parameter of the EXEC 
job control statement 

P = the total number of 

paragraph- names in a COBOL 
program 

• S = (87 2 + 5*V) bytes 

STN 



S =(72*PC*[ 19*LC4-[8*ON3+7*id]+£S ]) bytes 

TABLES ODOTAB 

where 

PC = the number of program control 
cards 

LC = the number of line control cards 

ON = the number of line control cards 
with OH options 

id = the number of identifiers 

requested on line-control cards 



ODOTAB = the size of ODOTAB on the 
debug file (approximately 27 
times the number of unique 
objects of OCCURS DEPENDING ON 
statements) . 

S =(818*S ♦ [S ])bytes 

DM BSAM QSAM 

where 

S 
BSAM = 800 bytes = the space required 
for BSAM modules (when not in the 
LPA) 



QSAM = 1124 bytes = the space 

required for QSAM modules (when 
not on the LPA) and no QSAM files 
are used in the program 

The input/output device requirements for 
execution of the problem program are 
determined from specifications made in the 
Environment Division of the source program. 
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SORT/HERGE FEATURE CONSIDERATIONS 



The basic requirements for use of the 
Sort/Herge feature are: 



A Systes/370 with sufficient sain 
storage to accommodate the load module 
to be executed, plus a minimum of 
32,000 bytes for execution of the 
sort/merge program, and any additional 
main storage assigned to the sort/merge 
program via the SORT-CORE-SIZE special 
register. 



* At least one mass storage device (which 
may be the system residence device) for 
residence of SYS1.SORTLIB. 



• At least three tape units or one mass 
storage device for intermediate 
storage. 

• The OS/VS Sort/Serge program product, 
5740-SM1. {If only the Sort feature is 
to be used — without alternate collating 
sequence and without Merge — then the OS 
Sort/Herge program product, 5734-SH1, 
would suffice as well.) 
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A PPEND IX A: SAM PLE PROGRAM OOflPUT 



The following is a sample COBOL program 
and the output listing resulting from its 
compilation, linkage editing, and 
execution. The program creates a blocked, 
unlabeled, physical sequential file, writes 
it out on tape, and then reads it back in. 
It also does a check on the field called 
NO-OF-DEPENDENTS. All data records in the 
file are displayed. Those with a zero in 
the HO-OF-DEPENDENTS field are displayed 
with the special character Z. The records 
of the file are not altered from the time 
of creation, despite the fact that the 
HO-OF-DEPEHDENTS field is changed for 
display purposes. The individual records 
of the file are created using the 



subscripting technique. TRACE is used as a 
debugging aid during program execution. 

The output formats illustrated in the 
listing are described in "Output.* 
Individual parts of the listing are 
numbered in accordance with the numbers 
used in the chapter "Output." 



Note; This program contains a logic error 
that causes abnormal termination at 
execution time so that the use of program 
checkout facilities can be illustrated. 
See the chapter "Symbolic Debugging 
Features." 



CCCCl 
00C02 
0CC03 
0O0C4 
0CCC5 
C0CC6 
00007 
00CC8 
CO0C9 
COCiO 
00011 
00 012 
00013 
C0C14 
00015 
0OC16 
G0C17 
00C18 
CCC19 
C0C20 
00021 
C0C22 
0002J 
J0C24 
O0C25 
0OC2t> 
0CC27 
00028 
OO029 
CCC30 
3O031 
00C32 
0CC33 
00 034 
CO035 
C0036 
00C37 
CCC28 
0OC39 
00040 
0OC41 
00042 
C0C43 
0OC44 
00 043 
CCC46 
00C47 
0CC48 
CCC49 
C0050 
00051 
00CJ2 
JO0J3 
C0C54 



100010 IDENTIFICATION 0IVISI0N. 

100020 PROGRAM-I0. TESTRUN. 

10003u AUTHOR. PROGRAMMER NAME. 

10004m INSTALLATION. NEW YORK PROGRAMMING CENTER. 

100050 DATE-WRITTEN. JULY 12, 1968. 

ICOO60 DATE-COMPILED. AUG 6,1976. 

10007o REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 

10008o COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK AS 

10009J INPUT. 

IOOIOu ENVIRONMENT DIVISION. 

100110 CONFIGURATION ScCTION. 

100120 SOURCE-COMPUTcR. IBM-360-H50. 

10013u OBJECT-COMPUTtR. IBM-360-H50. 

10014o INPUT-OUTPUT SECTION. 

100150 FILE-CONTROL. 

100160 SELECT FILE-1 ASSIGN TO UT-2400-S-SAMPLE. 

10017O SELECT FILE-2 ASSIGN TO UT-2400-S-SAMPLE. 

10018u DATA DIVISION. 

10019o FILE SECTION. 

100200 FD FILE-1 

100210 LABEL RcCORoS ARE OMITTED 

100220 BLOCK CONTAINS 100 CHARACTERS 

10022a RECORD CONTAINS 20 CHARACTERS 

100230 RECORDING MuDE IS F 

10024o DATA RECORD IS RECORD-1. 

10025o 01 RECORD-1. 

100260 02 FIELD-A PICTURE IS X(20). 

100270 FD FILE-2 

10028O ' LABEL RECORjS ARE OMITTED 

100290 BLOCK CONTAINS 5 RECORDS 

100300 RECORD CONTAINS 20 CHARACTERS 

100310 RECORDING MuDE IS F 

100320 DATA RECORD IS RECORD-2. 

10033O 01 RECORD-2. 

100340 02 FIELD-A PICTURE IS X(20). 

100350 WORKING-STORAGE SECTION. 

100360 77 KOUNT PICTURE S99 COMP SYNC. 

10037o 77 NOMBER PICTURE S99 COMP SYNC. 

10037a 01 FILLER. 

100380 02 ALPHABET PICTURE X(26) VALUE "ABCDEFGHI JKLMNOPQRSTUVWXYZ". 

100393 02 ALPHA REuEFINES ALPHABET PICTURE X OCCURS 26 TIMES. 

10040.. 02 DEPENDENTS PICTURE X(26) VALUE "0123401234012340123401234 

100410- "0". 

10042o 02 DEPEND RcDtFINES DEPENDENTS PICTURE X OCCURS 26 TIMES. 

1C044O 01 WORK-RECORo. 

100450 02 NAME-FIclD PICTURE X. ft 

10046o 02 FILLER PICTURE X VALUE IS SPACE. ° 

10047o 02 RECORD-Nu PICTURE 9999. 

100480 02 FILLER PICTURE X VALUE IS SPACE. 

100490 02 LOCATION PICTURE AAA VALUE IS "NYC". 

100500 02 FILLER PICTURE X VALUE IS SPACE. 
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0CC55 
00C56 
0CC57 
00058 
CCC59 
0CC60 
C0C61 
CO062 
CCU3 
J0Q64 
CCC45 
U0C66 
0CC67 
0CC6A 
O0C69 
CQC70 
0CC71 
0C072 
CCC73 
0CC74 
C0C75 
C0C76 
00077 

occ7a 

OCC79 

cocao 
cocai 

G0C62 
O0C£3 
00C£4 
0CC45 
C0C£6 



100510 
100520 
100521 
10052 t 
10052.. 
10053o 
1O054O 
100550 
1O056U 
10057u 
10058u 
10059o 
10060o 
100610 
100620 
100630 
100640 
10065 o 
10066J 
10067u 
10068u 
100690 
1C0700 
100 71k 
100720 
10073u 
10073i 
10074k 
1CC750 
100760 
10077O 
10078U 

INTRNL 

DNM=1 

0NM=1- 

0NM=1- 

DNM=i 

DNM=1 

DNM=1- 

DNM=1- 

DNM=1- 

DNM=i- 

ONM=i- 

DNM=1- 

DNM=1- 

DNM=1- 

0NM=1- 

DNM=1- 

0NM=1- 

DNM=1- 

DNM=1- 

DNM=1- 

DNM=1- 

DNM=2 

DNM=2 

DNM=2 

DNM=2 

DNM=<i 



02 NO-OF-DtPENDENTS PICTURE XX. 

02 filler picture xm value is spaces. 

01 RECORDA. 

02 A PUTURE S9(4) VALUE 1234. 

02 B RtuEFINES A PICTURE S9(7) COMPUTATIONAL-3. 
PROCEDURE DIVISION. 
BEGIN. 

THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 

* AND INITIALIZES COUNTERS. 

STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT NOMBER. 

THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE 

* CONTAINED I* THE FILE, WRITES THEM ON TAPE, AND DISPLAYS 
THEM ON THE CONSOLE. 

STEP-2. ADO 1 To KuUNT, ADO 1 TO NOMBER, MOVE ALPHA (KOUNT J TO 

NAME-FIELD. 

MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS. 

MOVE NOMBER TO RECORD-NO. 
STEP-3. DISPLAY WORK-RECORD UPON CONSOLE. WRITE RECORD-1 FROM 

WORK-RECORD. 
STEP-4. PERFORM STtP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26. 

* THE FOLLOWING CLOSES OUTPUT AND REOPENS IT AS 
" INPUT. 

STEP-5. CLOSE FiLE-1. OPEN INPUT FILE-2. 

* TnE FOLLOWING REAOS BACK THE FILE ANO SINGLES OUT 
' EMPLOYEES WITH NO DEPENDENTS. 

STEP-6. READ FI*_E-2 RECORD INTO WORK-RECORD AT END GO TO STEP-8. 

COMPUTE o = B + 1. 
STEP-7. IF NO-UI-- OtPENDENTS IS EQUAL TO "0" MOVE "Z" TD 

NO-OF-DEPENOENTS. EXHIBIT NAMED WORK-RECORD. GO TO 

STEP-6. 
STEP-8. CLOSE FiLE-2. 

STOP RUN. 



NAME 
148 • 
,.68 
189 
«:06 
<c26 
47 
<:67 
•i82 
^98 
iLZ 
■^30 
^»48 
•a68 
■i84 
•408 
■*ZQ 
442 
-461 
-475 
-493 
-000 
-026 
-04 
-o60 
-071 



LVL 

FD 
01 
02 
FD 
01 
02 
77 
77 
01 
02 
02 
02 
02 
01 
02 
02 
02 
02 
02 
02 
02 
02 
01 
02 
02 



SOURCc NAME 

FILE-i 

RECORU-1 

FIELD- A 

FILE-*: 

RECORu-2 

FIELD-A 

KOUNT 

NOMBEk 

FILLEK 

ALPHAoET 

ALPHA 

DEPENDENTS 

DEPENO 

WORK-kECORD 

NAME-rlELD 

FILLEK 

RECORu-NU 

FILLEK 

LOCATION 

FILLEK 

NO-OF-DEPENDENTS 

FILLEK 

RECORJA 

A 

B 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE R Q ■* 


DCB=01 




DNM= 1-148 




QSAM 


^ 


BL=1 


000 


DNM=1-168 


DS 0CL20 


GROUP 




BL = 1 


000 


DNM=l-189 


DS 20C 


DISP 




DCB=02 




DNM=l-206 




QSAM 


F 


BL=2 


000 


DNM=l-226 


DS 0CL20 


GROUP 




BL = 2 


000 


DNM=l-247 


DS 20C 


DISP 




BL=3 


000 


ONM= 1-267 


DS 1H 


COMP 




BL=3 


002 


DNM=l-2 82 


DS 1H 


COMP 




BL=3 


008 


DNH= 1-298 


DS 0CL52 


3 ROUP 




BL=3 


008 


DNM=1-312 


DS 26C 


DISP 




BL = 3 


008 


DNM=l-330 


DS 1C 


DISP R 




BL=3 


022 


DNM= 1-348 


DS 26 C 


DISP 




BL = 3 


022 


DNM=l-368 


DS 1C 


DISP P 




BL=3 


040 


DNH = 1-384 


DS 0CL20 


GROUP 




BL=3 


040 


DNM= 1-408 


DS 1C 


DISP 




BL = 3 


041 


DNM=l-428 


DS 10 


DISP 




BL=3 


042 


DNM= 1-442 


DS 4C 


DISP-NM 




BL=3 


046 


DNM=1-461 


DS 1C 


DISP 




BL=3 


047 


DNM= 1-475 


DS 3C 


DISP 




BL=3 


04A 


DNM=1»493 


DS 1C 


DISP 




BL = 3 


04B 


DNM=2-000 


DS 2C 


DISP 




BL=3 


04D 


DNM= 2-026 


DS 7C 


DISP 




BL=3 


058 


DNM=2-040 


DS 0CL4 


GROUP 




BL=3 


058 


DNM=2-060 


DS 4C 


DISP-NM 




BL=3 


058 


DNM=2-071 


DS 4P 


COMP-3 R 





462 



MEMORY MAP 




TGT 


00318 


SAVE AREA 


00318 


SWITCH 


00360 


TALLY 


00364 


SORT SAVE 


00368 


ENTRY-SAVE 


0036C 


SORT CORE SIZE 


00370 


RET CODE 


00374 


SORT RET 


00376 


WORKING CELLS 


00378 


SORT FILE SIZE 


004A8 


SORT MODE SIZE 


004AC 


PGT-VN T8L 


004B0 


TGT-VN TBL 


004 B4 


RESERVED 


004B8 


LENGTH OF VN TBl 


004BC 


LABEL RET 


004BE 


RESERVED 


004BF 


OBG R14SAVE 


004C0 


COBOL INDICATOR 


004C4 


A(INITl) 


004C8 


DEBUG TABLE PTR 


004CC 


SUBCOM PTR 


004D0 


SORT-MESSAGE 


004D4 


SYSOUT DDNAME 


004 DC 


RESERVED 


0040D 


COBOL ID 


004DE 


COMPILED POINTEK 


O04E0 


COUNT TABLE ADOKESS 


004E4 


RESERVED 


004E8 


DBG R11SAVE 


004F0 


COUNT CHAIN ADDRESS 


004F4 


PRBL1 CELL PTR 


004F8 


RESERVED 


004FC 


TA LENGTH 


00501 


RESERVED 


00504 


PCS LIT PTR 


0050C 


DEBUGGING 


00510 


CD FOR INITIAL INPUT 


00514 


OVERFLOW CELLS 


00518 


BL CELLS 


00518 


DECBADR CELLS 


00524 


FIB CELLS 


00524 


TEMP STORAGE 


00528 


TEMP STORAGE-2 


00530 


TEMP STORAGE-3 


00530 


TEMP STORAGE-4 


00530 


BLL CELLS 


00530 


VLC CELLS 


00538 


SBL CELLS 


00538 


INDEX CELLS 


00538 


SUBADR CELLS 


00538 


ONCTL CELLS 


00540 


PFMCTL CELLS 


00540 


PFMSAV CELLS 


00540 


VN CELLS 


00544 


SAVE AREA =2 


0054C 


SAVE AREA «=3 


0054C 


XSASW CELLS 


00554 


XSA CELLS 


00554 


PARAM CELLS 


00554 


RPTSAV AREA 


00558 


CHECKPT CTR 


00558 


DEBUG TABLE 


00558 
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61 * BEGIN 







0005E4 










PN=02 


EQU 


* 










0005E4 










START 


EQU 


* 










0005 E4 


58 


BO 


C 


060 




L 


11,080(0.12) 


PBL = 1 








0005E8 


58 


FO 


c 


024 




L 


15,024(0,12) 


V(ILBOFLWl) 








0005 EC 


05 


IF 








BALR 


1,15 










0005EE 


OOJ0003D 




DC 


X'00000030' 






64 


*STEP-1 


0005F2 










PN=03 


EQU 


* 










0.005F2 


58 


FO 


c 


024 




L 


15,024(0,12) 


V(ILBOFLWl) 








0005F6 


05 


IF 








BALR 


1,15 










0005F8 


00000040 




DC 


X'00000040« 






64 


OPEN 


0005FC 
000600 


58 
05 


FO 
EF 


c 


028 




L 
BALR 


15,028(0,12) 
14,15 


VULB0DBG4) 








000602 


58 


10 


c 


040 




L 


1,040(0,12) 


DCB=1 








000606 


58 


40 


1 


024 




L 


4,024(0,1) 










00060A 


02 


02 


4 


Oil C 


020 


MVC 


011(3,4) ,020(12) 




V(ILBOEXTO) 






000610 


50 


10 





234 




ST 


1,234(0,13) 


SA3=1 








000614 


92 


OF 





234 




MVI 


234(13) ,X'OF' 


SA3 = 1 








000618 


96 


80 


D 


234 




01 


234( 13),X'80' 


SA3=1 








0006 1C 


41 


10 





234 




LA 


1,234(0,13) 


SA3=1 








000620 


02 


03 


D 


060 C 


057 


MVC 


060(4,13) ,057(12) 


WC=01 


LIT + 7 






000626 


58 


FO 


C 


030 




L 


15,030(0,12) 


V(ILBOaiOO) 








00062A 


05 


EF 








BALR 


14,15 










00062C 


58 


10 


C 


040 




L 


1,040(0,12) 


0CB = 1 








000630 


02 


03 





060 C 


05B 


MVC 


060(4, 13), 058(12) 


WC=01 


LIT+11 






000636 


58 


FO 


c 


030 




L 


15,030(0,12) 


V(ILBOQIOO) 








00063A 


05 


EF 








BALR 


14,15 










00063C 


58 


70 





200 




L 


7,200(0,13) 


BL =1 




64 


MOVE 


000640 


02 


01 


6 


000 C 


050 


MVC 


000(2, 6), 050(12) 


DNM=l-267 


LIT + O 






000646 


02 


01 


6 


002 C 


050 


MVC 


002(2, 6), 050(12) 


DNM=l-282 


LIT+O 


68 


*STEP-2 


00064C 










PN=04 


EQU 


* 










00064C 


58 


FO 


C 


024 




L 


15,024(0,12) 


V(ILBOFLtfl) 








000650 


05 


IF 








BALR 


1,15 










000652 


00u00044 




DC 


X'00000044' 






68 


ADD 


000656 


48 


30 


c 


052 




LH 


3,052(0,12) 


LIT+2 








00065A 


4A 


30 


6 


000 




AH 


3,000(0,6) 


DNM=l-267 








0006 5E 


40 


30 


6 


000 




STH 


3,000(0,6) 


DNM=l-267 




68 


ADO 


000662 


48 


30 


C 


052 




LH 


3,052(0,12) 


LIT+2 








000666 


4A 


30 


6 


002 




AH 


3,002(0,6) 


0NM=l-282 








00066A 


40 


30 


6 


002 




STH 


3,002(0,6) 


0NM=l-282 




68 


MOVE 


00066E 


41 


40 


6 


008 




LA 


4,008(0,6) 


DNM=l-330 








000672 


48 


30 


6 


OOO 




LH 


3,000(0,6) 


DNM= 1-267 








000676 


5C 


20 


C 


050 




M 


2,050(0,12) 


LIT+O 








00067A 


1A 


43 








AR 


4,3 










00067C 


58 


40 


C 


050 




S 


4,050(0,12) 


LIT+O 








000680 


50 


40 





220 




ST 


4,220(0,13) 


SBS=1 








000684 


58 


EO 





220 




L 


14,220(0,13) 


SBS=1 








000688 


02 


00 


6 


040 E 


000 


MVC 


040(1, 6), 000(14) 


DNM=l-408 


DNM=l-333 


7C 


MOVE 


00068E 


41 


40 


6 


022 




LA 


4,022(0,6) 


DNM=l-368 








000692 


48 


30 


6 


OOO 




LH 


3,000(0,6) 


DNM=l-267 








000696 


5C 


20 


C 


050 




M 


2,050(0,12) 


LIT+O 








00C69A 


1A 


43 








AR 


4,3 










00069C 


5B 


40 


C 


050 




S 


4,050(0,12) 


LIT+O 








0006 AO 


50 


40 





224 




ST 


4,224(0,13) 


SBS=2 








0006 A4 


58 


FO 





224 




L 


15,224(0,13) 


SBS = 2 





k6H 





0006A8 


02 


00 


6 


04B F 




0006AE 


92 


40 


6 


04C 


MOVE 


0006B2 


40 


30 


6 


002 




0006B6 


4E 


30 





210 




00066A 


F3 


31 


6 


042 D 




0006CO 


96- 


FO 


6 


045 


*STEP-3 


0006 C4 












0006C4 


58 


FO 


C 


024 




0006C8 


05 


IF 








0006CA 


00u00048 


DISPLAY 


0006CE 


58 


FO 


C 


028 




000602 


05 


EF 








0006 D4 


58 


FO 


c 


034 




000608 


05 


IF 








0006DA 


0uu2 








0006DC 


00 










000600 


00i>014 






0006EO 


00J00208 




0006 E4 


00%0 








0006 E6 


FFFF 






WRITt 


0006ES 


58 


FO 


c 


028 




0006 EC 


05 


EF 








0006EE 


D2 


13 


7 


000 6 




0006 F4 


58 


10 


c 


040 




00O6F8 


18 


21 








0006FA 


92 


00 


2 


07A 




0006FE 


58 


40 


2 


024 




00 07 02 


92 


00 


4 


014 




000706 


96 


01 


4 


01B 




00070A 


58 


10 


C 


040 




00070E 


58 


FO 


C 


030 




000712 


02 


03 


D 


060 C 




000718 


58 


00 


1 


04C 




00071C 


44 


00 


1 


060 




000720 


58 


20 


C 


40 




000724 


91 


40 


2 


07A 




000728 


92 


00 


2 


07A 




00072C 


47 


10 


B 


154 




000730 


50 


10 





200 




000734 


58 


70 


D 


200 




000738 












000738 












000738 


58 


10 





22C 




00073C 


07 


Fl 






♦STEP-4 


00073E 












0O073E 


58 


FO 


c 


024 




000742 


05 


IF 








000744 


00u0004A 


PERFURM 


000748 


02 


03 





228 




00074E 


41 


00 


b 


172 




000752 


50 


00 





22C 




000756 












000756 


48 


30 


6 


000 




00075A 


49 


30 


C 


054 




00075E 


47 


80 


B 


182 



22C 







MVC 


04B(1, 6), 000(15) 


DNM=2-0 






MVI 


04C(6),X , 40' 


DNM=2-D+1 






LH 


3,002(0,6) 


DN*=l-282 






cvo 


3,210(0,13) 


TS=01 






UNPK 


042(4,61,216(2,13) 


DNM=l-442 






01 


045(6), X'FO' 


DNM> 1-442+3 


PN= 


= 05 


EQU 


* 








L 


15,024(0,12) 


V( ILB0FLW1) 






BALR 


1,15 








DC 


X , 00000048« 








L 


15,028(0,12) 


V(ILS0DeG4) 






BALR 


14,15 








L 


15,034(0,12) 


V( ILBOOSPO) 






BALR 


1,15 








DC 


X'0002' 








DC 


X'OO' 








DC 


X' 000014* 








DC 


X'0D0OC2O8' 


BL =3 






DC 


X'0040« 








DC 


X'FFFF' 








L 


15,026(0,12) 


V(ILB00BG4) 






BALR 


14,15 








MVC 


000(20, 7), 040(6) 


DNM=1-168 






L 


1,040(0,12) 


DCB=1 






LR 


2,1 








MVI 


07A(2),X , 00' 








L 


4,024(0,2) 








MVI 


014(4), X'OO' 








01 


01B(4),X'01' 








L 


1,040(0,12) 


DC3 = 1 






L 


15,030(0,12) 


V( ILB03ID0) 






MVC 


060(4,13) ,05F(12) 


KC=01 






L 


0,04C(0,1) 








EX 


0,060(0,1) 








L 


2,040(0,12) 


DC3 = 1 






TM 


07A(2),X'40« 








MVI 


07A(2) ,X'00' 








BC 


1,154(0,11) 


GN=07 






ST 


1,200(0,13) 


BL =1 






L 


7,200(0,13) 


BL =1 


GN= 


= 07 


EQU 


* 




GN= 


=01 


EQU 


* 








L 


1,22C(0,13) 


VN=01 






BCR 


15,1 




PN= 


= 06 


EQU 


* 








L 


15,024(0,12) 


V(ILBCFLWl) 






BALR 


1,15 








OC 


X«0000004A' 








MVC 


228(4, 13), 22CU3) 


PSV=1 






I.A 


0,172(0,11) 


GN=02 






ST 


0,22C(0,13) 


VN=01 


GN= 


= 02 


EQU 


* 








LH 


3,000(0,6) 


DNM= 1-2 6 7 






CH 


3,054(0,12) 


LIT+4 






BC 


8,182(0,11) 


GN=03 



DNM=l-368 



ONM= 1-384 
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000762 


47 


FO 


B 


068 






000766 














000766 


02 


03 


D 


22C D 


228 


STEP-5 


00076C 














00076C 


58 


FO 


C 


024 






000770 


05 


IF 










000772 


00u00040 




CLOSc 


000776 

00077A 


58 

05 


FO 

EF 


C 


028 






00077C 


58 


10 


C 


040 






000780 


91 


10 


1 


030 






000784 


05 


50 










000786 


47 


80 


5 


01A 






00078A 


05 


01 


1 


02A C 


063 




000790 


47 


70 


5 


01A 






000794 


58 


20 


1 


04C 






000798 


48 


20 


1 


052 






00079C 


50 


20 


1 


04C 






0007A0 


58 


10 


C 


40 






0007A4 


50 


10 





234 






0007A8 


92 


40 





234 






00C7AC 


96 


80 


D 


234 






0007B0 


41 


10 





234 






000764 


02 


03 





060 C 


06 5 




00078A 


58 


FO 


C 


030 






00078E 


05 


EF 










0007C0 


58 


10 


C 


040 






0007C4 


D2 


03 


D 


060 C 


05B 




0007CA 


58 


FO 


C 


030 






0007CE 


05 


EF 










0007DO 


58 


50 


D 


1B0 






0007D4 


50 


50 


D 


200 






000708 


58 


20 


C 


040 






0007DC 


91 


01 


2 


017 






0007EO 


47 


10 


B 


21C 






0007E4 


58 


10 


2 


014 






0007E8 


96 


01 


2 


017 






0C07EC 


IB 


44 










0007EE 


43 


40 


1 


005 






0007F2 


4C 


40 


1 


006 






0007F6 


41 


00 


4 


008 






0007FA 


41 


10 


1 


000 






0007FE 


OA 


OA 










000800 












OPEN 


000800 
000804 


58 
05 


FO 
EF 


c 


028 






000806 


58 


10 


c 


044 






00080A 


58 


40 


1 


024 






OO080E 


D2 


02 


4 


Oil C 


020 




000814 


50 


10 





234 






000618 


92 


00 





234 






00081C 


96 


80 


D 


234 






000820 


41 


10 





234 






000824 


02 


03 





060 C 


057 




00082A 


58 


FO 


c 


030 






00082E 


05 


EF 









BC 


15.068(0.11) 


PN=04 




EQU 


* 






MVC 


22C(4, 13), 228(13) 


VN=01 


PSV=1 


EQU 


* 






L 


15.024(0.12) 


VULB0FLW1) 




BALR 


1,15 






DC 


X« 00000040' 






L 


15,028(0,12) 


VULB0DBG4) 




BALR 


14,15 






L 


1,040(0,12) 


0CB=1 




TM 


030( U.X'IO' 






8ALR 


5,0 






BC 


8,01A(0,5) 






CLC 


02A(2,1). 063(12) 




LIT+19 


BC 


7,01A(0,5) 






L 


2,04C(0,1) 






SH 


2,052(0,1) 






ST 


2,04C(0,1) 






L 


1,040(0,12) 


DCB = 1 




ST 


1,234(0,13) 


SA3=1 




MVI 


234( 13) ,X'40« 


SA3=1 




01 


234( lSJ.X'SO' 


SA3=1 




LA 


1.234(0,13) 


SA3 = 1 




MVC 


060( 4,13), 065( 12) 


WC = 01 


LIT«-21 


L 


15,030(0,12) 


VULB02IOO) 




BALR 


14,15 






L 


1,040(0,12) 


DCB = 1 




MVC 


060(4, 13), 05B(12) 


WC=01 


LIT*11 


L 


15,030(0,12) 


V(ILBOQIOO) 




BALR 


14,15 






L 


5,180(0,13) 






ST 


5,200(0,13) 


BL =1 




L 


2,040(0,12) 


0CB=1 




TM 


017(2) ,X'01' 






BC 


1,21C(0.11) 


GN=08 




L 


1,014(0,2) 






01 


017(2) ,X«01« 






SR 


4,4 






IC 


4,005(0,1) 






MH 


4,006(0,1) 






LA 


0,008(0,4) 






LA 


1,000(0,1) 






SVC 


10 






EQU 


* 






L 


15,028(0,12) 


VULB0DBG4) 




BALR 


14,15 






L 


1.044(0.12) 


0CB=2 




L 


4,024(0,1) 






MVC 


011(3, 4), 020(12) 




V( IL90EXT0) 


ST 


1,234(0,13) 


SA3 = 1 




MVI 


234(13),X'00' 


SA3=1 




01 


234(13) ,X'80' 


SA3 = 1 




LA 


1,234(0,13) 


SA3 = 1 




MVC 


060(4, 13), 057(12) 


WC=01 


LIT+7 


L 


15,030(0,12) 


V(ILBOQIOO) 




BALR 


14,15 







466 







00C83O 


58 


10 


C 


044 








000834 


02 


03 


D 


060 C 


05B 






00083A 


58 


FO 


C 


030 








C0083E 


05 


EF 












000840 


58 


80 





204 




8C 


*STEP-6 


000844 
















000844 


58 


FO 


c 


024 








000848 


05 


IF 












00084A 


OOJ00050 




80 


READ 


00084E 
000852 


58 
05 


FO 

EF 


c 


028 








000854 


58 


10 


c 


044 








000858 


18 


21 












0C085A 


02 


O-i 


2 


021 C 


03 D 






000860 


D«£ 


03 


D 


060 C 


069 






000866 


58 


FO 


C 


030 








00086A 


05 


Er 












00086C 


50 


10 





204 








C00870 


58 


80 


D 


2 04 








0008 74 


02 


13 


6 


040 8 


00 






00087A 


47 


Fu 


8 


29E 








00087E 












80 


GO 


00087E 
000882 


47 


FO 


8 


306 




81 


COMPOTE 


000882 


F8 


70 


D 


210 C 


056 






000888 


FA 


43 


D 


213 6 


058 






00088E 


F8 


33 


6 


058 


214 


62 


♦STEP-7 


0CC894 
















000894 


58 


FO 


C 


024 








000898 


05 


IF 












00C89A 


0Ou0OO52 


> 




82 


IF 


00089E 


95 


FO 


6 


04B 








0008A2 


47 


70 


8 


202 








0008A6 


95 


40 


6 


04C 








0008AA 


47 


70 


6 


2D2 




82 


MOVE 


0008AE 


92 


E9 


6 


04 B 








0008 62 


92 


40 


6 


04C 








00C8B6 












63 


EXHIoIT 


0008B6 


58 


10 


C 


070 








0008 BA 


50 


10 





23C 








00086E 


41 


20 


D 


23C 








0008C2 


58 


FO 


C 


028 








0008C6 


05 


EF 












0C08C8 


58 


FO 


c 


034 








0008CC 


05 


IF 












0008CE 


80ul 












0008DO 


10 














000801 


OOuOOB 










0008D4 


0Co00074 








0008 D8 


OOuO 












00080A 


00 














0008DB 


00O014 










0008DE 


ODu00208 








0O08E2 


00*0 












0008E4 


FFFF 









L 


1,044(0,12) 


0CB = 2 




MVC 


060(4, 13), 05B(12j 


rfC=01 


LIT+11 


L 


15,030(0,12) 


V(ILBOQIOO) 




BALR 


14,15 






L 


8,204(0,13) 


BL =2 




EQU 


* 






L 


15,024( 0,12) 


V(ILeOFLWl) 




BALR 


1,15 






OC 


X« 00000050' 






L 


15,028(0,12) 


VULB0DBG4) 




BALR 


14,15 






L 


1,044(0,12) 


DCB = 2 




LR 


2,1 






MVC 


021(3, 2), 030(12) 




GM=04+1 


MVC 


060(4,13) ,069(12) 


WC=01 


LIT*?? 


L 


15,030(0,12) 


V(ILB03I00) 




BALR 


14,15 






ST 


1,204(0,13) 


BL =2 




L 


8,204(0,13) 


BL =2 




MVC 


040(20,6) ,000(8) 


0NM=l-384 


DNM=l-2?o 


BC 


1E,29E(0,11) 


3N=05 




EQU 


* 






BC 


15,306(0,11) 


PN=010 




EQU 


* 






ZAP 


210(8, 13), 056(1, 12) 


TS = 01 


LIT+6 


AP 


213(5, 13), 058(4, 6) 


TS=04 


ONM=2-71 


ZAP 


058(4, 6), 214(4, 13) 


DNM=2-71 


TS=04+1 


EQU 


* 






L 


15,024(0,12) 


V(ILBOFLHl) 




BALR 


1,15 






DC 


X'00aO0052' 






CLI 


046(6) ,X«FO' 


0NM=2-D 




BC 


7,202(0,11) 


GN=06 




CLI 


04C(6),X«40' 


0NM=2-D+1 




BC 


7,202(0,11) 


GN=06 




MVI 


04B(6),X'E9' 


DNM=2-0 




MVI 


04C(6) ,X'40' 


0NM=2-0+l 




EQU 


* 






L 


1,070(0,12) 


LIT+32 




ST 


1,23C(0,13) 


PRM=1 




LA 


2,23C(0,13) 


PRM=1 




L 


15,028(0,12) 


VULB0DPG4) 




BALR 


14,15 






L 


15,034(0,12) 


V(ILBODSPO) 




BALR 


1,15 






DC 


X'8001' 






DC 


X'10* 






DC 


X'OOOOOB' 






DC 


X'0C000074' 


LIT+36 




DC 


X'OOOO' 






DC 


X'OO' 






OC 


X'000014' 






DC 


X'0D000208' 


BL =3 




DC 


X'0040' 






DC 


X'FFFF' 
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83 


GO 


0008E6 


47 


FO 


8 


260 


85 


*STEP-8 


0C08EA 














0008EA 


58 


FO 


C 


024 






0008EE 


05 


IF 










0008F0 


00u00055 


85 


CLOSc 


0008F4 
0C08F8 


58 
05 


FO 
EF 


C 


028 






0O08FA 


58 


10 


c 


044 






0O08FE 


91 


10 


1 


030 






C0C902 


05 


50 










000904 


47 


80 


5 


01A 






000908 


D5 


01 


1 


02A C 063 






00090E 


47 


70 


5 


01A 






000912 


58 


20 


1 


04C 






000916 


48 


20 


1 


052 






00091A 


50 


2u 


1 


04C 






00091E 


58 


10 


C 


044 






0GC922 


50 


10 





234 






000926 


92 


40 


D 


234 






00092A 


96 


80 





234 






00092E 


41 


10 


D 


234 






000932 


02 


03 





060 C 065 






C00938 


58 


FO 


C 


030 






00093C 


05 


EF 










00093E 


58 


10 


C 


044 






000942 


02 


03 


D- 


060 C 05B 






000948 


58 


FO 


C 


030 






00094C 


05 


EF 










00094E 


58 


50 





1B0 






000952 


50 


50 





204 






0C0956 


58 


20 


c 


044 






00095A 


91 


01 


2 


017 






00095E 


47 


10 


B 


39A 






000962 


58 


10 


2 


014 






000966 


96 


01 


2 


017 






00096A 


IB 


44 










00096C 


43 


40 


1 


005 






000970 


4C 


40 


1 


006 






000974 


41 


00 


4 


008 






000978 


41 


10 


1 


000 






0009 7C 


OA 


OA 










0C097E 










86 


STOP 


00097E 
0C0982 
000984 


58 
05 


FO 
EF 


C 


028 






G 009 84 


58 


FO 


C 


038 






000988 


07 


FF 










00098A 


50 


00 


5 


008 






00098E 


50 


50 





004 






00C992 


50 


EO 





054 






000996 


91 


20 





048 






00099A 


47 


EO 


F 


02E 






00099E 


58 


20 





1B8 






0009 A2 


91 


40 


D 


049 






0009A6 


47 


EO 


F 


02E 






0009AA 


96 


04 


2 


000 



15,260(0,11) 



PN=010 EQU 


* 


L 


15,02410,12) 


BALK 


1,15 


DC 


x'ooooooss 1 


L 


15,028(0,12) 


BALR 


14,15 


L 


1,044(0,12) 


TM 


030(1), X'10' 


BALR 


5,0 


BC 


8,01A(0,5) 


CLC 


02A(2,1), 063(1?) 


BC 


7,01A(0,5) 


I 


2,04C(0,1) 


SH 


2,052(0,1) 


ST 


2,04C(0,1) 


L 


1,044(0,12) 


ST 


1,234(0,13) 


MVI 


234(13) ,X«40' 


01 


234(13),X'80' 


LA 


1,234(0,13) 


MVC 


060(4,13) ,065(12) 


I 


15,030(0,12) 


BALR 


14,15 


L 


1,044(0,12) 


MVC 


060(4, 13), 05BI12) 


L 


15,030(0,12) 


BALR 


14,15 


L 


5,180(0,13) 


ST 


5,204(0,13) 


L 


2,044(0,12) 


TM 


017(2), X'01« 


BC 


1,39A(0,11) 


L 


1,014(0,2) 


01 


017(2), X'Ol' 


SR 


4,4 


IC 


4,005(0,1) 


MH 


4,006(0,1) 


LA 


0,008(0,4) 


LA 


1,000(0,1) 


SVC 


10 


GN=09 EQU 


* 


L 


15,028(0,12) 


BALR 


14,15 


GN=010 EQU 


* 


L 


15,038(0,12) 


BCR 


15,15 


INIT2 ST 


13,008( 0,5) 


ST 


5,004(0,13) 


ST 


14,054(0,13) 


TM 


048(13) ,X'20* 


BC 


14,02E(0,15) 


L 


2,168(0,13) 


TM 


049(13) .X^O' 


BC 


14,02E(0,15) 


01 


000(2),X'04' 



V(ILBOFLHl) 

VULB00PG4) 
0CB=2 



LIT*19 



DC3=2 
SA3=1 
SA3 = 1 
SA3=1 
SA3=1 
WC=01 
V( ILBOQIOO) 

DCB = 2 
WC=01 
V(ILeOQIOO) 



BL =2 
0C8=2 



VIILB0D8G4) 
V(ILBOSRVl) 



SWT + 1 
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0009AE 


sa 


FO 


2 


038 


0009B2 


41 


FO 


F 


004 


0009B6 


07 


FF 






0009 B8 


94 


EF 





048 


0C09BC 


58 


FO 


C 


010 


0O09C0 


05 


EF 






0009C2 


12 


00 






0009C4 


07 


89 






0009C6 


96 


1C 





048 


0009CA 


58 


FO 


c 


014 


0009CE 


05 


EF 






000900 


05 


FO 






0009D2 


9J. 


20 





048 


000906 


47 


EO 


F 


016 


00090A 


58 


00 


B 


048 


C009DE 


98 


20 


B 


050 


0009 E2 


58 


EO 





054 


0009E6 


07 


FE 






0009E8 


96 


20 


D 


048 


0009 EC 


41 


60 





004 


0009F0 


41 


10 


C 


OOC 


0009 F4 


41 


70 


C 


OOF 


00C9F8 


05 


50 






G009FA 


5a 


40 


1 


OOC 


0009FE 


It 


4B 






000A00 


50 


40 


1 


000 


C0OAO4 


87 


16 


5 


000 


OOOAOB 


41 


10 


C 


03C 


OOOAOC 


41 


70 


c 


047 


COOA10 


05 


50 






00CA12 


58 


40 


1 


000 


000A16 


IE 


4B 






0OOA18 


50 


40 


1 


000 


000A1C 


87 


16 


5 


000 


000A20 


41 


60 





008 


000A24 


41 


10 


c 


048 


000A28 


41 


70 


c 


04F 


000A2C 


05 


50 






OO0A2E 


58 


40 


1 


000 


0OOA32 


IE 


46 






000A34 


50 


40 


1 


000 


0O0A38 


87 


16 


5 


000 


000A3C 


41 


80 





200 


OOOA40 


41 


60 





004 


000A44 


41 


70 





20F 


000A48 


05 


10 






0O0A4A 


58 


00 


8 


000 


000A4E 


1^ 


00 






000A50 


47 


80 


1 


010 


0OOA54 


IE 


OB 






0OOA56 


50 


00 


8 


000 


O0OA5A 


87 


86 


1 


000 


00OA5E 


58 


60 


D 


2C8 


00OA62 


58 


70 


D 


200 


000A66 


58 


80 





204 


000A6A 


02 


07 





22C 


000A70 


58 


EO 


D 


054 



C 048 



L 

LA 

BCR 

NI 

L 

BALR 

LTR 

BCR 

01 

L 

BALR 

BALR 

TM 

BC 

L 

LM 

L 

BCR 

01 

LA 

LA 

LA 

BALR 

L 

ALR 

ST 

BXLE 

LA 

LA 

BALR 

L 

ALR 

ST 

BXLE 

LA 

LA 

LA 

BALR 

L 

ALR 

ST 

BXLE 

LA 

LA 

LA 

BALR 

L 

LTR 

BC 

ALR 

ST 

BXLE 

L 

L 

L 

MVC 

L 



15t036(0,2) 

15,004(0,15) 

15,15 

048(13) ,X«EF' 

15,010(0,12) 

14,15 

0,0 

8,9 

048(13) ,X'10' 

15,014(0,12) 

14,15 

15,0 

0^8(13), X«20« 

14,016(0,15) 

0,048(0,11) 

2,13,050(11) 

14,054(0,13) 

15,14 

046(13) ,X'20' 

6,004(0,0) 

1,00C(0,12) 

7,00F(0,12) 

5,0 

4,000(0,1) 

4,11 

4,000(0,1) 

1,6,000(5) 

1,03C(0,12) 

7,047(0,12) 

5,0 

4,000(0,1) 

4,11 

4,000(0,1) 

1,6,000(5) 

6,008(0,0) 

1,048(0,12) 

7,04F(0,12) 

5,0 

4,000(0,1) 

4,11 

4,000(0,1) 

1,6,000(5) 

8,200(0,13) 

6,004(0,0) 

7,20F(0,13) 

1,0 

0,000(0,8) 

0,0 

8,010(0,1) 

0,11 

0,000(0,8) 

8,6,000(1) 

6,208(0,13) 

7,200(0,13) 

8,204(0,13) 

22C(8, 13), 048(12) 

14,054(0,13) 



SWT+O 
VIR=1 



SWT+O 
VI* = 2 



PN=01 
VNI=1-1 



VNI = 1 
LIT+0-1 



0VF = 1 
TS=01-1 



BL =3 
BL =1 
BL =2 
VN=01 
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000A74 


07 FE 


OOCOOO 


90 EC OOC 


000004 


18 50 


000006 


05 FO 


000006 


45 80 F 010 


OOOOOC 


E3C5E2E3D9E4D540 


000014 


E5c2D9Fl 


000018 


07 00 


00001A 


96 9F F 024 


00001E 


07 FF 


000020 


96 02 1 034 


000024 


07 FE 


000026 


41 FO 001 


00002A 


07 FE 


00002C 


00o009CA 


000030 


OOuOCOOO 


000034 


OOciOOOOO 


000038 


00*00560 


00003C 


O0J00318 


000040 


OOclO05E4 


000044 


00u0098A 


G00048 




0C0084 


OOuOOOOO 


000088 


FlF54faF5F84BF0F5 


000090 


Clc4C74040F66B40 


000098 


Flr9F7F6 



BCR 


15,14 


STM 


14,12,00C(13) 


LR 


5,13 


BALR 


15,0 


BAL 


8,010(0,15) 


DC 


X , £3C5E2E3D9E«D540» 


oc 


X'E5E2D9F1' 


BCR 


0,0 


LM 


9,15,024(15) 


BCR 


15,15 


01 


034(1) f X'02' 


BCR 


15,14 


LA 


15,001(0,0) 


BCR 


15,14 


A DC ON 


L4UNIT3) 


ADC ON 


L4UNIT1) 


A DC ON 


L4(INIT1) 


A DC ON 


L4(PGT) 


A DC ON 


L41TGT) 


A DC ON 


LUSTART) 


ADCON 


L4UNIT2) 


OS 


15F 


DC 


X'OOOOOOOO' 


DC 


X , F1F54BF5F84BF0F5' 


DC 


X' CI E4C740*OF66B40 • 


DC 


X , F1F9F7F6« 
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♦STATISTICS* 



SOURCE RECORDS 



86 



DATA DIVISION STATEMENTS = 



25 



PROCEDURE DIVISION STATEMENTS 



?1 



♦options in effect* 
♦options in effect* 
♦options in effect* 
♦optiuns in effect* 

♦CPTIuNS IN EFFECT* 
♦OPTIONS IN EFFECT* 
♦OPTIUNS IN EFFECT* 



SIZE = lii.072 BUF = 12288 LINECNT = 57 SPACE!, FLAGW, SEQ, SOURCE 

DMAP, PMAP, NOCLIST, NOSUPMAP, NOXREF, SXREF, LOAD, NODECK, QUOTE, NOTPJIMC, FL?W= 10 

NOTERM, NONUM, NOBATCH, MONAME, COMPILE=01, NOSTATE, NORESIDENT, NODYNAM, NPLIB, NPSYNTAX 
OPTIrtUE, SYMDMP, NOTEST, VERB, ZWB, SYST, NOENDJOB, NOLVL 

NOLST , NOFDECK,NOCDECK, LC0L2, L120, DUMP , NUADV , NOPRINT, 

NOCOUN.T, NOVBSUM, NOVBREF, LANGLVU2) 

OEBUG FILE SIZE = 2 BLOCKS, 1024 BYTES 



CARC ERROR MESSAGE 



CROSS-REFERENCE DICTIONARY 



CATA NAMES 



A 

ALPHA 

ALPHABET 

B 

DEPEND 

DEPENDENTS 

FIELD- A 

FIELU-A 

FILE-1 

FILE-2 

KCLNT 

LCCATION 

NAME-FIELD 

NO-OF-DEPENDcNTS 

NCMBtR 

RECCRD-NO 

RECORD-1 

PtCCRD-2 

RECQkDA 

hCRK-RECORD 



DEFN 


REFERENCE 




000058 








000044 


000068 






000043 








000059 


000081 






O00047 


000070 






000045 








000029 








000037 








000017 


000064 


000072 


000077 


000018 


000077 


000080 


000085 


000040 


000064 


000068 


000070 000074 


000053 








000049 


000068 






000055 


000070 


000082 




000041 


000064 


000068 


000071 


o 00051 


000071 






000028 


000072 






000036 


000080 






000057 








000048 


000072 


000080 


000083 



PRCCEOURE NAMES 



DEFN 



REFERENCE 



BEGIN 

STEP-1 

STEP-2 

STEP-3 

STEP-4 

STEP-5 

S1EP-6 

STEP-7 

S1EP-8 



000061 
u 00064 
000068 
000072 
000074 
O00077 
000080 
000082 
000085 



000074 
000074 



000083 



14 
58 



IKFlloil-W 
IKF21*0I-W 



IBM-370 IS ONLY VALID COMPUTER-NAME. I6M-36d SPECIFICATION IGNORED. 
PICTURE CLAUSE IS SIGNED, VALUE CLAUSE UNSIGNED. ASSUMED POSITIVE. 
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APPENpiX B: C OBOL LIBRARY SUBROUTINES 



COBOL library subroutines perform 
operations that require such extensive 
coding that it would be inefficient to 
place the coding in the object aiodule each 
time it is needed. 

COBOL library subroutines are stored in 
the COBOL library (SYS 1. COBLIB) . The 
required subroutines are inserted in load 
modules by the linkage editor. 

There are several major categories of 
COBOL library subroutines, namely: 
subprograi linkage, object -time program 
operations {i.e., data conversions, 
arithmetic operations, test conditions, 
data manipulation, data management, and 
special features) , and object-time 
debugging. The categories are described in 
this order. 

Figure 17 4 later in this chapter 
includes a list of COBOL library 
subroutines, their storage reguirements, 
and the associated calling information. 

In addition, Q routines, which are not 
classified as COBOL library subroutines, 
are used to calculate the length of 
variable-length fields and the location of 
variably located fields resulting from an 
OCCURS clause with a DEPENDING ON option. 



Bhen a program finishes execution, this 
routine deletes all the subroutines called 
by the program except those subroutines 
that are being used by another program in 
the region/partition. It also deletes any 
subprogram in the CANCEL literal or CANCEL 
identifier statement. 



N_OBES, Init ia lization Subrou tine 



The ILBGBEGO subroutine performs 
initialization functions when the NORES 
option is in effect. If the Subroutine 
Communications Area (SUBCOM) has not been 
link edited, it loads the area and checks 
whether its calling program is the main 
program or a subprogram. 



Object -Time Options Subro utine fIL.BOPR«pj„ 



This subroutine is invoked dynamically 
(by either ILBONTRO or ILBOBEGO) to scan 
the user's object- time options and set 
internal switches and options accordingly. 



STOP RON Subroutine.., (ILBOSRVO) 



SUBROUTINES FOR SUBPRQGRAH LINKAGE 



The subroutines that control the loading 
of library subroutines or subprograms and 
the exiting from programs or subprograms 
are described here. 



The ILBOSRV subroutine is called by all 
programs compiled by the OS/VS COBOL 
compiler. {For pre-OS/VS compatibility an 
ILBOSTPO entry point is also provided.) 
This routine returns control to the system, 
if the calling program is the main program, 
or to the caller, if it is not. 



ENTER Subroutine {ILBONTRO),, 



J2I 02_JIi!_I« s sa qes_ Subroutine {ILBOMSGO) 



The ILBONTRO subroutine is used {1) when 
the RESIDENT option is an effect, to load 
one copy of each subroutine called by the 
main program or any of its subprograms into 
any region/partition; and (2) when the 
DYNAM option is in effect, to call any 
subprogram specified in a CALL literal or 
CALL identifier statement, first loading it 
if it has not already been loaded into that 
region/partition. {If insufficient storage 
is available for loading, the user's ON 
OVERFLOW imperative statement is called, if 
one was specified.) 



The ILBOBSGO subroutine determines 
whether or not a message is to be issued. 
If a message is to be issued this 
subroutine formats and issues it. 



STOP RUN Termin ation Subroutine (ILBQSTTO) 



The ILBQSTTO subroutine performs 
termination functions at the end of 
execution of the COBOL program if the 
ENDJOB option is in effect. 
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OBJECT-TI«E PROGRAM OPERATIONS 



COBOL LIBRARY CONVERSION SUBROUTINES 



internal decimal, and from internal decimal 
to numeric edited are done in-line. The 
other conversions are performed by the 
COBOL library subroutines shown in Figure 
172, and by the separate sign subroutine. 



Eight numeric data formats are permitted 
in COBOL — five external (for input and 
output) and three internal (for internal 
processing) . 

The five external formats are these: 

(1) external or zoned decimal, (2) external 
floating-point, (3) sterling display, 

<4) numeric edited, and (5) sterling 
report. The three internal formats are 
these: (1) internal or packed decimal, 

(2) binary, and (3) internal 
floating-point. 

The conversions from internal decimal to 
external decimal, from external decimal to 



S^Barate„§ijgn_ Subroutine jILBOSSNO) 



The ILBOSSNO subroutine converts 
separately signed data-names to internal 
decimal format and then checks for a valid 
sign. If the sign is valid, this 
subroutine generates the corresponding 
overpunch in the receiving field. If not, 
it causes an object time message to be 
issued and the job to be terminated. 
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Subroutine Name 

and 

Entry Points 



Conversion 



From 



To 



— i 

\ 

-H 



IIB0EFL2 
ILB0EFL1 
ILBOEFLO 



External Floating-point 
External Floating-point 
External Floating-point 



Internal Decimal 

Binary 

Internal Floating-point 



ILBOBIDO* 

ILB0BID11 
ILB0BID2* 



Binary 



Internal Decimal 



ILBOBIEOi 
ILB0BIE1* 
ILBQBIE2* 



Binary 



External Decimal 



—I 



ILBOBII02 



ILB0BII12 



Binary 



Internal Floating-point 



ILBOTEFO* 
ILB0TEF12 
IIB0TEF2 
IFB0TEF3 



Binary 

Internal Decimal 
Internal Floating-point 



External Floating-point 

External Floating-point 
External Floating-point 



-H 



ILBOIDBO 



ILB0IDB1 



Internal Decimal 
External Decimal 



Binary 
Binary 



3 ILB0DCI1 

I 

I ILBODCIO 

I 



Internal Decimal 
External Decimal 



Internal Floating-point 
Internal Floating-point 



J 



I 



ILBOIFDO 



ILB0IFD1 



1 



Internal Floating-point 
Internal Floating-point 



I 



Internal Decimal 
External Decimal 



J 1 The entry points used depend on whether the double-precision number is in registers 

J and 1, or 2 and 3, or 4 and 5, respectively. 

f^The entry points are for single-precision binary and double- precision binary, 

| respectively. 

j3*This entry point is used for calls from other COBOL library subroutines. 

I : : : 

Figure 172. Functions of COBOL Library Conversion Subroutines fPart 1 of 2) 
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Subroutine Name 
and 
Entry Points 



Conversion 



From 



To 



ILB0IFB1 

ILB0IFB23 
ILBOIFB03 



Internal Floating-point 



Internal Floating-point 



Binary integer and a power 
of 10 exponent- 
Binary 



ILBOIDR0 



Internal Decimal 



Sterling Report 



ILBOIDTO 



Internal Decimal 



Sterling Non-Report 



ILBOSTI0 



Sterling Non-Report 



Internal Decimal 



— + 



ILBOCVB0 



External decimal 



Binary 



ILB0CVB1 



External decimal 



Binary 



*The entry points used depend on whether the double-precision number is in registers 

and 1, or 2 and 3, or 4 and 5, respectively. 
2 The entry points are for single-precision binary and double-precision binary, 

respectively. 
3This entry point is used for calls from other COBOL library subroutines. 
i 

Figure 17 2. Functions of COBOL Library Conversion Subroutines (Part 2 of 2) 



I Subroutine Name 



Function 



J 
-I 



1ILBOXMO0 



Internal Decimal Multiplication (30 digits * 30 digits = 60 digits) | 



JILBOXDIO 



Internal Decimal Division (60 digits/30 digits = 60 digits) 



I 



JILBQXPR0 
| 



Exponentiation of an Internal Decimal Base by a Binary Exponent 



— 4 



JILBOFPW0 
| 



Floating-point Exponentiation 



IILBOGPW0* 
h 



Floating-point Exponentiation 



pThe ILBOGPW0 entry point is used if the exponent has a picture specifying an integer. | 
| The ILBOFBW0 entry point is used in all other cases. \ 

i , j 

Figure 173. Function of COBOL Library Arithmetic Subroutines 



Appendix B: COBOL Library Subroutines 475 



COBOL LIBRARY A8ITHMETIC SUBROUTINES 



Host arithmetic operations are performed 
in-line. However, involved calculations, 
such as exponentiation, and calculations 
with very large numbers, such as decimal 
multiplication of two 30-digit numbers, are 
performed by COBOL library subroutines. 
These subroutine names and their functions 
are given in Figure 173. 



COBOL LIB8ABY SUBROUTINES POS TESTING 
CONDITIONS AT OBJECT TIME 



Several subroutines are used to test 
conditions that determine the path of 
control the object program selects. Such 
subroutines are described below. 



figurative constant must always be the 
second operand. If it is first in the 
source program, the operands are reversed 
and the condition code to be passed on is 
inverted before this subroutine is called. 



COBOL LIBRARY DATA MANIPULATION SUBROUTINES 



Subroutines are used to manipulate data 
in main storage in response to the MOVE, 
TRANSFORM, STRING, and UNSTRING statements, 
{Data manipulation in response to the 
EXAMINE statement is performed in-line by 
the object program.) 



MOVE Subroutine (XLBOVMQQ and ILBQVMQ1) 



Class Test subroutine (ILBQCLSO) 



The ILBOCLSO subroutine is used to 
perform class tests for variable-length 
items and those fixed-length items over 256 
bytes long, to determine whether a field is 
alphanumeric. 

U°.£§* The following tables are placed in 
the library for use by the in-line coding 
generated and the subroutines called for by 
both class test and TRANSFOEM: 



ILBOATBO - 
ILBOETBO - 



ILBOTRNO - 
ILBOUTBO - 



- alphabetic class test 
external decimal class 
test 

ILBOITBO — internal decimal class 
test 
transformation 

- unsigned internal decimal 
class test 

ILBOWTBO — unsigned external decimal 
class test 



COMPARE Subroutine (ILBOYCOO) 



This subroutine is used to handle some 
MOVE statements. The subroutine is also 
used for READ and WRITE statements 
processed in conjunction with the SAME 
RECORD AREA clause. The subroutine has 
two entry points, depending on the type 
of move: ILBOVMOO (left- justified) and 
ILBOVM01 (right- justified) . 

MOVE Subroutine for System/370 (ILBOSMVO) 



This special MOVE subroutine is used 
when the length of the receiving field is 
either greater than 512 bytes or variable. 
The subroutine transfers characters to a 
right- justified receiving field. 



MOVE t o Alpha numeric-Edited Fi el d 
Subroutine (I.LBOANE0), 



The ILBOANEO subroutine moves a 
data-name, literal, or figurative constant 
into a right- or left-justified 
alphanumeric edited field. 



The ILBOVCOO subroutine compares two 
operands, one or both of which are of 
variable lengths. They may exceed 256 
bytes. 



MOVE to Numeric- Edite d Fie ld subroutine 
iHtlQNEDO}. 



Comp are with Figurati ve Constant Subro utine 
"fILBOIVLO) 



The ILBONEDO subroutine is called by the 
UNSTRING subroutine to move characters from 
a packed decimal field into a 
numeric-edited receiving field. 



The ILBOIVLO subroutine compares the 
identifier to a figurative constant. The 
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MOVE Figurative Constat (ILBLOANFO) 



The ILBLOANF subroutine moves a 
figurative constant of more than one 
character into a right- or left- justified 
nonnumeric receiving field. 



TRANSFpRH Subroutine fILBOVTRO) 

The ILBOVTRO subroutine translates 
variable- length items. 



STRING,,, Subroutine (ILBOSTGO) 



The ILBOSTGO routine combines the 
partial or complete contents of two or more 
subfield(s) into a single field. This 
routine transfers characters from the 
sending item{s) to the receiving item in 
the same way that moves from alphanumeric 
item(s) to alphanumeric item (s) are 
effected. 



DISPLAY, TRACE, and EXHIBIT Subroutine 
(ILBODSPO) 



The ILBODSPO subroutine is used to 
print, punch, or type data, usually in 
limited amounts, on an output unit. TRACE 
and EXHIBIT are kinds of DISPLAY. 

The acceptable forms of data for this 
subroutine are: 

1. Display 

2. External decimal 

3. Internal decimal {converted by the 
subroutine to external decimal) 

4. Binary (converted by the subroutine to 
external decimal) 

5. External floating-point 

Internal floating-point numbers must be 
converted to external floating-point 
numbers- before the subroutine is called. 

Note: If the contents of a data-name are 
such that when converted they will exceed 
18 decimal digits, the ILBODSPO subroutine 
cannot process them and the results are 
unpredictable. 



QNSTRING Subroutine (ILBOUSTO) 



The ILBOUSTO routine separates 
continuous data in a sending field, placing 
it in multiple receiving fields. 



INSPECT Subroutine (ILBOINSQ) 



This subroutine performs operations for 
the INSPECT statement, doing specified 
tallying and replacing. 



DISPLAY Subroutine {ILBODSSO) 



The ILBODSSO subroutine prints or types 
data of a certain kind on SYSPRINT or at 
the console. This subroutine is used 
instead of ILBODSPO when there are no 
reguests by the program for TRACE or 
EXHIBIT, and no variable-length or 
floating-point items; when there are no 
reguests for display upon SYSPONCH; and 
when neither the RESIDENT nor the DYNAM 
option is in effect. 



ACCEPT Subroutine IILBOACPO) 



COBOL LIBRARY DATA MANAGEMENT SUBROUTINES 



COBOL lib 
process the 
TRACE, EXHIB 
key is speci 
WRITE (QSAM 
OPEN (QSAM o 
RECEIVE (TCA 
subroutines 
printer spac 
seguence, an 



rary subroutines are called to 

following verbs: DISPLAY, 

IT, ACCEPT, START <when generic 

fied) , READ {QSAM or BSAM) , 

or BSAM), CLOSE (QSAH or BSAM), 

r BSAM), REHRITE (QSAM), 

M) , and SEND (TCAM) ; library 

are also called for I/O errors, 

ing, alternate collating 

d printer overflow. 



The TLB 
read from 
console at 
logical re 
the size o 
less than 
appear as 
within the 
the data i 
characters 
are read u 
to the dat 
item is gr 



OACPO subrout 
SYSIN or from 

execution ti 
cord size of 
f the data it 
80 characters 
the first set 

input record 
tem is greate 
, as many rec 
ntil the stor 
a item is fil 
eater than 80 



ine is called to 

the operator's 
me. For SYSIN, a 
80 is assumed. If 
em being accepted is 
, the data oust 

of characters 
If the size of 
r than 80 
ords as necessary 
age area allocated 
led. If the data 

characters, but is 
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not an exact Multiple of 80, the remainder 
of the last logical record is not 
accessible. For the console, a maximum of 
114 characters are accepted and either 114 
characters or the length of the item, 
whichever is smaller, is moved to the 
operand named in the ACCEPT statement. 



Error Intercept Subro uti ne (ILBOSYNO) 



The ILBOSYN0 subroutine performs, for 
version 4 and OS/VS, the same operations as 
the ILBOERR0 subroutine described above. 
The following list shows the entry point 
that is used for the various access 
methods: 



Generic Key START Subroutine (ILBOSTRO) 



The ILBOSTS0 subroutine is called when 
USING KEY clause is coded with the START 
verb for ISAM files. The subroutine 
formats the search argument so that data 
management can get control to search for 
the generic key. 



Entry Point 


Access 


ILB0SYN1 


QSAM 


ILBOSYN2 


BSAH 


ILBOSYN3 


BDAM 


ILBOSYN4 


QISAM 


ILB0SYN5 


BISAH 



Label Bandling^§ub£outine jILBOLBLO) 



Checkpoint Subroutine (ILBOCKPO) 



The ILBOLBL0 subroutine is called for 
beginning- of-volume and beginning-of-f ile 
label processing or at end-of-file and 
end-of-volume. 



The ILBOCKP0 subroutine generates a 
checkpoint record, continuing the status of 
a program when a checkpoint is taken. This 
record is written on a checkpoint data set. 



Hait Subroutine flLBOWAT) 



This subroutine allows its caller to 
wait a specified amount of time. 



Printe r Overflow Subroutin e (ILBOPTVO) 



The ILBOPTV0 subroutine is used to 
control printer overflow testing and page 
ejection. 



Printer Spacing Subroutine ( ILBOSP A0) 



The ILBOSPA0 subroutine is used to 
control printer spacing. 



Eirror Interce pt Subroutine (ILBpERRO) 



The ILBOE 
for various 
control to t 
specified in 
or to the US 
depending on 
handling opt 
points used 
ILBOERR0 are 



RRO subroutine is used to test 
error conditions, and passes 
he interpretive-statement 

the INVALID KEY option phrase 
E FOR ERROR declarative section 

the type of error and error 
ions specified. The entry 
for error processing by 



ILBOERR1 Physical Sequential Files 

ILBOERR2 Direct and Relative Files 

Accessed sequentially 
ILBOERR3 Indexed Files Accessed 

Sequentially 
ILBOEER4 Direct and Relative Files 

Accessed Randomly 
ILBOERR5 Indexed Files Accessed 

Randomly 



BSAH WRITE /CLOSE and BDAM OPEN Subroutine 
(ILBOSAM0) 



The ILBOSAM0 routine processes 
input/output statements for direct or 
relative files accessed sequentially. It 
also handles OPEN statements and CLOSE 
statements with the REEL option for 
directly organized output files accessed 
randomly. 



I S. A a_gS A.p_3JUh£oatine ,. jl LBQS£]jOL 



The BSAH read routine reads segments of 
a logical record and assembles them into a 
complete logical record. The routine is 
called by a compiler-generated READ code 
for a spanned record direct BSAH file. 
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Q SAM I/O Subroutine CILBOQIpl 



with the input queue associated with the 
cdname specified in the RECEIVE statement. 



This subroutine handles the various I/O 
requests for COBOL QSAM files. 



DCB Exit Sub routin e (ILBQEyTO) 



The ILBOEXTO subroutine is called as a 
DCB exit routine during an OPEN for a QSAM 
file to add the record format (EECFH) 
parameter options to the standard DCB. 



VSAM Initialization subroutine ( ILBOINTO) 



The ILBOINTO subroutine is used to 
obtain virtual storage for the VSAM File 
Control Block (FCB) associated with each 
VSAM File Information Block (FIB) . 



Qu eue Analyzer phJect-Time Subroutine 
ilLBOSQAO) 



The ILBOSQAO subroutine is included for 
pre-OS/VS compatibility purposes only. It 
is called by the ILBORECO routine if the 
COBTPQD data set is present. This routine 
searches the COBTPQD data set for a member 
that corresponds to the name in the 
SYMBOLIC QUEDE field (defined in the COBOL 
source statements). If a match is found, 
the analyzer reads the member into main 
storage, using it to validate the SYMBOLIC 
SOB-QUEUE name(s) in the input CD of the 
COBOL source program. The analyzer also 
identifies the first valid DD name for the 
queue structure and gives this name to the 
ILBORECO routine. 



VS AM Open and Clo s e Subr outine ( ILBOVOCO l 



The ILBOVOCO subroutine is used for all 
VSAM open and close requests. 



VS AM Actio n Request Subroutine {ILBOVjCOO) 



The ILBOVIOO subroutine is used for all 
START, READ, REWRITE, WRITE, and DELETE 
verbs that refer to VSAM files. 



Queue Structure Descripti on Subroutine 
(ILBOOSUO) 



The ILBOQSUO subroutine creates a 
partitioned data set with one member for 
each queue structure defined in the 
COBOL- like source statements. This routine 
also generates a printed listing of the 
structure element, as well as of error 
messages, if any. 



RECEIVE Subrout ine ( ILBORECO) 



For RECEI 
subroutine t 
segment, or 
segment from 
the COBOL ap 
MESSAGE COUN 
returns the 
the queue st 
updates the 
(CD) entry. 



VE requests, the ILBORECO 
ransfers a message, a message 
part of a message or message 

the message control program to 
plication program. For ACCEPT 
t requests, the subroutine 
number of completed messages in 
ructure. This routine always 
input communication description 



R ECEIVE Initialization subroutin e 
IlLBQfiNTPl. 



The ILBORNTO subroutine is included for 
pre-OS/VS compatibility purposes only. It 
builds the control block that communicates 



Message Count s ubroutine (IL BOMSC ) 

This subroutine provides the caller with 
a count of the complete messages on a 
specified queue. 



Queue structure Scan (Communications) 

Subroutine (ILBOOSS) 



This subroutine traverses the queue 
structure identified by the input CD and 
returns successive ddnames representing 
elementary subqueue names. 



Job Schedu ler Subroutine fllLBOSCDl 



This subroutine schedules a specified 
job by issuing the operator START command. 
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ENAg LE/p iSABLE Subroutine fILBONBL), 



This subroutine modifies the message 
control tables in response to ENABLE and 
DISABLE statements. 



Co mmunications Job S c heduler Utility 
(ILBOCJS) 



This utility schedules jobs when there 
are messages on TCAM queues for them to 
process. 



Declarative Save Area Chaining S ub r outine 
(ILBOCHNO), 



The ILBOCHNO subroutine acquires a 
dynamic save area for a Declarative entry 
condition; chains together the save areas 
created for the Error and Label 
Declaratives routines; releases save areas 
from the chain when the Declarative routine 
processing is complete. 



control block that communicates with the 
output queue associated with the cdname 
specified in the SEND statement. 



COBOL LIBRARY SUB80UTINES FOB SPECIAL 
FEATORES 



Subroutines are used for some of the 
special features of COBOL: 

• Sort/Merge feature 

• Table handling feature (SEARCH 
statement) 

• segmentation feature (GO TO statement) 

• 3886' Optical Character Reader 
» ABEND request 

• Alternate collating sequence 

Also, a subroutine is called in response to 
the use of the following special registers: 

CURRENT-DATE, DATE, DAY, TIME, and 
TIME-OF-DAY. 



GETCORE Subroutine (ILBOCMMO) 



The ILBOCfltiO subrouti 
GETHAIN and FREEHAIN mac 
the COBOL program or for 
subroutine requiring sto 
deletions. The subrouti 
the information about th 
acquired through the GET 
instruction and releases 
from the chain when the 
instruction is issued fo 
storage. 



ne issues the 

ro instructions for 

any COBOL library 
rage additions or 
ne chains together 
e storage areas 
JSAIN macro 

this information 
FREEMAIN macro 
r that area of 



SEND Su broutine (ILBOSNDQl 



Sggt/flerge Feature. Subroutine (ILBOSRTO) 



The ILBOSRTO subroutine acts as an 
interface between the COBOL calling program 
and the Sort/Merge program via the entry 
point name SORT. 



Merge subroutine (ILBOMRGO) 



The ILBOMSGO subroutine acts as an 
interface between the COBOL calling prograi 
and the Sort/Merge program for merge 
operations. 



The ILBOSNDO subroutine transfers a 
message, a message segment, or part of a 
message or message segment from the COBOL 
application program to the message control 
program. This routine always updates the 
output CD entry. 



Sort Subroutine jILBOSMGO) 



The ILBOSMGO subroutine is used by the 
Merge subroutine for sorting required by 
merge operations. 



SEND In itialization Subr outine ( ILBOSNTOjl 



The ILBOSNTO subroutine (ILBOSNTO) 
subroutine is included for pre-os/VS 
compatibility purposes only. It builds the 



SQrt.Debag^Subrgutine (ILBO5DB0) 



The ILBOSDBO subroutine is used for 
sorting a debug data set. 
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Al ternate Collating Sequen ce Compare 
Subroutine (IL BOACS) 



This subroutine handles the various 
forms of non-numeric comparisons, using an 
alternate program collating seguence (if 
specified) . It also handles "native" 
collating seguences. 



ILB0DTE3 — year day 
ILB0DTE4 - 



- hour minute second 
hundredth of a second 



3886 .Optical Character Reader Interface 
Subroutine (ILBOOCRpr 



SEARCH Subroutine (ILBOSCHO) 



The ILBOSCHO subroutine performs a 
binary search on a specified level of a 
table. It is used for the SEARCH ALL 
statement. 



S egmenta t ion Subro ut ine (ILBQSGMO) 



The ILBOSGMO subroutine is included for 
pre-OS/VS compatibility purposes only. It 
is used to load segments of a program that 
are not in main storage and to pass control 
from one segment to the 'other . 



The ILBDOCRO subroutine handles all 
input/output operations with the 3886 
Optical Character Reader and builds the OCR 
File Control Block required for this 
purpose. 



ABEND Reguest subroutine (ILBQABNO) 

The ILBOABNO subroutine is used to 
process all ABEND requests. 



OBJECT-TIME DEBUGGING 



GO TO DEPENDING ON Subroutine (ILBOGDQO) 



The ILBOGDOO subroutine u 
of a particular data-name as 
a list of constants for each 
and then transfers control t 
PN. If the value of the dat 
greater than the number of P 
control returns to the next 
after the calling sequence, 
handles transfer of control 
segments, and any necessary 
reinitialization. 



ses the value 
an index into 
PN specified 

o the proper 

a- name is 

N's specified, 

instruction 
ILBODGOO also 

between 

segment 



D ate-and -Time Sub r outine flLBOD TEO) 



The options available for object-time 
debugging include: the statement number 
option (STATE) , the flow trace option 
(FLOW) , the count option (COUNT) , the 
symbolic debugging option (SYMDMP) , and the 
OSE FOR DEBUGGING declarative. The 
subroutines for the first two options 
provide debugging information at abnormal 
termination of a program; the subroutines 
for the other options provide debugging 
information either at abnormal termination 
or dynamically during the execution of a 
program. All of these subroutines are 
under the control of and are supervised by 
the debug control subroutine ILBODBGO. The 
debug control subroutine is described 
first, followed by the subroutines that are 
called in response to the specification of 
the STATE, FLOW, SYMDMP, and COUNT options. 



This group of subroutines performs five 
functions in response to the use of the 
special registers CURRENT-DATE, DATE, DAY, 
TIME, and TIHE-OF-DAY. The list below 
indicates the function of each of the entry 
points, and the format of each result in 
the receiving field of the specified MOVE 
or ACCEPT statement. 

ILBODTEO — month/day/year 

ILBODTE1 — hour minute second 

ILB0DTE2 — year month day 



Debug Control Subroutin e ( ILBODBGO) 



The ILBODBGO subroutine is called once 
at entry point ILBODBGO for each COBOL 
program for which any of the debugging 
options have been specified. This 
subroutine handles linkage and input/output 
for the STATE, FLOW, and SYMDMP options. 
It also produces the program name, the 
completion code, and the last PSW message 
at the time of the abnormal termination. 
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Use-for- Debugging Subroutine flLBQBUG) 



SYMDMP Error Message Subroutine {ILBODBEO) 



This subroutine handles invocation of 
USE FOE DEBUGGING declaratives, including 
filling in of the DEBUG-ITEM special 
register. 



The ILBODBEO subroutine is called by the 
PfilNT routine of the debug control 
subroutine to format the appropriate error 
message in the SYSDBOUT output buffer. 



Flow Trace Subroutine fllBOFLWO) 



The ILBOFLWO subroutine produces a 
formatted trace of the last "n" of COBOL 
procedures executed prior to an ABEND. It 
initializes, builds, and writes out the 
flow trace table. 



For additional information on the FLOW, 
STATE, and SYMDMP options and their 
relationship to other COBOL options, see 
the chapter entitled "Symbolic Debugging 
Features" and the section "options for the 
Compiler" in the chapter entitled "Job 
Control Procedures." 



Statement Num ber Subroutine. ... flLBOSTMQ) 



The ILBOSTNO subroutine processes the 
STATE option and determines both the card 
number and the verb number for the last 
statement executed before the ABEND, and 
then generates a message containing this 
information. 



COUNT Initial izati on Subrp utijP e ^il^BOTCOO^ 



The ILBOTCOO subroutine initializes the 
count common area, gets space for and 
initializes the count chain, and 
initializes the count chain pointer in the 
object module TGT. 



COUNT Frequency Subroutine {ILBOCT10 ) 



Symbolic Dump Subrou tine MLBQD10 an d 
ILBOD20) 



The ILBOD10 subroutine is called when 
the SYMDMP option is in effect; this 
routine calls other modules as necessary 
for SYHDMP initialization. The ILBOD20 
subroutine services SYMDMP output reguests 
from DBGO. SYMDMP generates the following 
information as output on the SYSDBOUT data 
set: a copy of all SYMDMP control 
statements; diagnostic messages; dynamic 
dumps of user-selected data areas at 
strategic points during program execution; 
an abnormal termination statement number 
message; and the complete abnormal 
termination dump. In addition, 
modifications are made to the COBOL program 
in main storage if dynamic dumping is 
reguested for the program. 



The ILBOCTiO subroutine updates the 
appropriate node counter by one and saves 
the caller's count-block number in the 
count chain. 



COUNT Term ination Subro uti ne MLBOTC20) 



The ILBOTC20 subrout 
termination of object ra 
determine if there are 
monitored. If so, it c 
ILBDTC30 to write ex ecu 
if the termination is n 
ILBDDBG8 to close the d 
the termination is not 
print file is left open 
information. 



ine is called at 
odule execution to 
programs being 
alls subroutine 
tion statistics, and 
ormal* calls 
ebug print file. If 
normal, the debug 
for debugging 



H2£e: When SYMDMP services are reguested 
for a job step, the seguence of events is, 
in general, as follows: (1) initialization 
— for the first COBOL program in a job 
step, then for all other COBOL programs in 
that job step, and finally for independent 
program segments; (2) processing — first 
for dynamic dump reguests, and then for 
abnormal termination dumps. 



COUNT Print Subroutine (ILBOTC30) 



The ILBOTC30 subroutine computes and 
writes execution statistics on the debug 
print file upon termination of the program 
being monitored. 
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OBJECT-TIME DEBUGGING UN DER INFORMATION 
MANAGEMENT SYSTEM (PP5734-XX6, ~57U0-XX2) 



SPIE Subroutine (ILBOSPIO) 



subroutine to return control with no action 
(SPIE is not issued) . 

Note . When this facility is used, the 
PSW in a SYSUDUMP will point to the 
SVG 13 in ILBOSPI. 



In order to ensure correct debug on 
SYSDBOUT, the ILBOSPIO subroutine is called 
by an explicit CALL statement written by 
the COBOL programmer in his source pro- 
gram to be compiled with the FLOW, STATE, 
SYMDMP, and/or COUNT options. 

There should be one CALL statement 
written at the beginning of the Procedure 
Division and following each ENTRY statement 
in the program. 

There should be one CALL statement 
written at each exit point in the program, 
i.e., preceding each GOBACK, EXIT PROGRAM, 
or STOP RUN statement. 

These CALL statements are effective only 
in a COBOL program compiled with FLOw", 
STATE, SYMDMP, or COUNT options. They must 
be executed as a logical pair only once per 
COBOL run unit. If COBOL program A calls 
COBOL program B, either A or B or both can 
be compiled with debugging options, but 
only the highest level program compiled 
with debugging options should contain CALL 
'ILBOSPIO* statements. The first execution 
of ILBOSPIO issues a SPIE macro instruction 
to trap the old program PS» in the event of 
a program check before STAE gets control at 
abnormal termination. The second execution 
of ILBOSPIO resets any previous SPIE at 
task normal termination. At abnormal 
termination, ILBODBGO will reset the 
previous SPIE. 

Finally, any CALL 'ILBOSPIO* statements 
written in a COBOL program compiled with 
none of the above options cause the 



CALLING AND 5T0RAG E .INFORMATION 



Figure 174 includes a list of COBOL 
library subroutines, their storage 
requirements, and the associated calling 
information. The subroutines are arranged 
alphabetically by the characters following 
'ILBO*. The list includes subroutines that 
are called directly by the object program 
— prifflary subroutines — and the 
subroutines they call — secondary 
subroutines. Some subroutines {for 
example, ILBOANE) function as both primary 
and secondary subroutines. 

The superscripts that accompany several 
of the entries refer to footnotes at the 
end of the table. Footnotes that appear 
with the names of subroutines indicate 
routines that are conditionally obtained, 
that are secondary subroutines only, or 
that may never reside in the OS/VS2 link 
pack area (LPA) or the OS/VS1 resident 
reenterable routine area (FRR) . The 
footnotes that appear with some of the 
numeric values indicate whether the 
information represents a maximum value, a 
minimum value, or an estimated value. In 
all cases, the numeric values represent 
decimal bytes rounded off to the nearest 
50. 

For descriptions of the primary 
subroutines and of the major secondary 
subroutines, see the sections of this 
appendix entitled "Subroutines for 
Subprogram Linkage," "Object-Time Program 
Operations," and "Object-Time Debugging." 
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i i 


1 

Yes 1 


| ILBOACP 
| (ACCEPT) 


Called by compiled 
code 


582 


100 


ILBOCMM 


100Q | 1 


Yes I 


IILBOACS 

| (Alternate compare) 


Called by compiled 
code and ILBOUNS, 
ILBOSTG, ILBOSCH, 
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260 1 








Yes | 
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| edited field) 


Called by compiled 
code and by 
ILBOUST 
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l 


None 




Yes | 


IILBOANF 

I (MOVE figurative 

| constant) 


Called by compiled 
code 
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None 




Yes | 


IILBOATB 

| (Alphabetic table 

| for class test) 


Used for ILBOCLS 


272 





None 




Yes | 


| ILBOBEG 

| (NORES 

I initialization) 


Called by compiled 
code and ILBOSRV 


29 6 




None 




Yes | 


IILBOBID 

| (Binary to internal 

| decimal) 


Called by compiled 
code 


136 





None 




Yes | 


| ILBOBIE 

| (Binary to external 

I decimal) 


Called by compiled 
code 


136 





None 




Yes | 


IILBOBII 

| (Binary to internal 

| floating-point) 


Called by compiled 
code and by 
ILBODCI, ILBOEFL 


488 





None 




Yes | 


IILBOBUG 

| (USE FOR DEBUGGING) 


Called by compiled 
code 


2060 


5602 


ILBOCHN 
ILBOCMM 


450 J 
1000 | 


Yes | 


IILBOCHN 

| (Save area chaining) 


ICalled by ILBOSYN 
and ILBOLBL 


432 




ILBOCMM 


11000 | 


Yes | 


IILBOCJS 

| (Job Scheduler) 


Called by operating 
system 






| ILBOMSC 
ILBOSCD 
ILBOWAT 


300 | 7220 
| 200 | 

I 150 | 


No | 
(also | 
non-re- I 
usable | 


IILBOCKP 

I (Checkpoint) 


Called by compiled 
I code 


| 74 





| None 




Yes | 


IILBOCLS 

| (Class test) 


Called by compiled 
| code 


| 168 


I o 






Yes I 



J L. 



♦Size given is an estimate. 
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ILBOD10, 
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ILBOREC, 


ILBOSND, 
















ILBONBL, 


ILBOQSS, 
















ILBOBOG, 


ILBOINS-, 
















and ILBOQIO 
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Link-edited or loaded 
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by compi 


led code 














| communications) 


and by ILBOSRV; 
















used by 
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Called by 
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Yes | 
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code 
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Called by 
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300S 
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Yes | 
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I by 
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ILBOUST 
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IILBODBG 


Called by 
code if 
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FLOW, 


3638 


952 7 
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STATE, or SYMDMP 
















is specified 






ILBOCMM 


950 
















ILBODBE 789 


1312 

















ILBOSTN 789 


776 


96 














ILBOFLW? 


1096 


600 37 




'. 










ILBOD01 78 « 


650 







|ILBOD01 78 » 


Called by 


ILBODBG if 


7 28 





ILBODIO 78 * 


2648 


4000 7 


Yes | 




SYSMDP is specified 






ILB0D11 7 «9 


775 

















ILB0D12 78 * 


1810 

















IILB0D13789 


1576 

















ILB0D14789 


1480 

















ILBOD20789 


1122 

















ILB0D21 78 * 


1680 


25/ODO 7 














ILB0D22 78 * 


2265 


1 o 














ILB0D23789 


3882 

















ILB0D24789 


2783 


1 o 














ILB0D25 78 « 


1222 

















ILBDD26 789 


2278 







IILBODCI 


Called by 


compiled 


( 240 




IILBOIDB 


150 





Yas | 


| (Decimal to internal 


I code 
















I floating-point) 


















IILBODCKO 


| Called by 
call 


explicit 


560 





None 






1 Yes | 


IILBODSP 


I Called by 


compiled 


[3520 


| 104 


IILBOCMM 


[ 950 




Yes | 


| (DISPLAY, TRACE, 


| code 
















| EXHIBIT) 
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_____ 
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i 

IILBODSS* | 
| (DISPLAY) 


Called 


by 


compiled 


1034 


i 




None 




i i 

1 No | 


IILBODTE 

I (Date, day, and 

| time) 


Called 
code 


by 


compiled 


50 4 





None 




1 Yes | 


| ILBOEFL 
| (Conversion 
| from external 
I floating-point) 


Called 
code 


by 


compiled 


600 





ILBOIOB 
ILBOBII 


150 
500 


1 I 
| Yes | 


IILBOERE 

| (Error intercept) 


Called 


by 


the system 


674 





None 




1 Yes | 


IILBOETB 

| (External decimal 
| table for class 
| test) 


Used bj 


ILBOCLS 


268 





None 




1 Yes | 


IILBOEXT 
| (DCB exit) 


Called 


by 


the system 


80 




None 




1 Yes | 


IILBOFLW 


Called' 
compi 
FLOW 


by ILBODBG and 
led code if 
is specified 


1340 


60037 


ILBOCMM 


1000 


1 Yes | 


IILBOFPW 

I (Floating-point 

| exponentiation) 


Called 
code 


by 


compiled 


816 





None 




1 Yes | 


IILBOGDO 

| (GO TO DEPENDING ON) 


Called 
code 


by 


compiled 


280 





None 




1 Yes | 


IILBOGPW 

| (Floating-point 

| exponentiation to a 

| binary exponent) 


Called 
code 


by 


compiled 


96 





None 




1 Yes | 


IILBOIDB 

| (Decimal to binary) 


Called 
code 


by 
or 


compiled 
by ILBODCI 


128 





None 




1 Yes | 


IILBOIDR 

| (Internal decimal 

| to sterling r-eport) 


Called 
code 


by 


compiled 


1680 





None 




1 Yes | 


| ILBOIDT 

| (Internal decimal to 

| sterling non- 

| report) 


Called 
code 


by 


compiled 


696 





None 




1 Yes | 


| ILBOIFB 

| (Internal 

| floating-point to 

| decimal or binary) 


Called by compiled 
code or by ILBOIFD 

I or ILBOTEF 


350 





None 




1 Yes | 


IILBOIFD 

I (Internal floating 
| to decimal or 
| binary) 


ICalled 
code 


by 


compiled 


224 





ILBOIFB 




1 Yes | 
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| constant) 


Called 
code 


by 


compiled 
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None 




I Yes | 


IILBOLBL 

| (Label handling) 


Called 


by 


the system 
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/ 


ILBOCHN 


450 


I Yes | 


IILBOMRG 
| (Merge) 


Called 


by 


ILBOSRT 


830 




None 




I Yes | 


IILBOMSC 

| (Message count) 


Called 


by 


ILBOCJS 


260 


7220 


None 




I Yss | 


IILBOMSG 

| (STOP RUN message) 


Called 


by 


ILBOSRV 
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ILBODBG 7 


2850 


I Yes | 


(ILBONBL 

| (ENABLE/DISABLE) 


Called 
code 


by 


compiled 
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ILBOCMM 
ILBOQSS 
ILBOREC 


1000 
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ILBONTR 
' (RES initialization) 


Called 
code 


by 


compiled 


3064 


384 2 


ILBOPRM 7 


1130 


Yes 


lILBOOCRii 

| (Optical character 

| reader) 


Called 
code 


by 


compiled 


1402 





None 




I No | 


IILBOPRM 

| (Object-time 

| parameters) 


Called by ILBONTR 
or ILBOBEG 


1130 




ILBONSND 


3300 


I Yes | 


IILBOPTV 

I (Printer overflow) 


Called 
code 


by 


compiled 


152 





None 




I Yes | 


IILBOQIO 
| (QSAM I/O) 


Called 
code 


by 


compiled 


1390 


1682 


ILBOCMM 
ILBOSYN 
ILBOSRV? 
ILBOSPA? 
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1050 
1000 
1800 


I Yes | 


IILBOQSS 

I (Queue scan) 


Called by 
ILBONBL 


ILBOREC, 
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48003 


None 




I Yes | 


IILBOQSU* io 

| (Queue structure 

| utility program) 


Called 


by 


JCL 
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4000 
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(usable) | 
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| Notes: 










j 1 . The size given 


is an estimate. 








j 2. The size given 


is a minimum. 








| 3. The size given 


is a maximum. 








| 4. The subroutine 


indicated may never reside in the OS/VS2 link pack 


area (LPA) or the 




| OS/VS1 resident 


reusable routine area (RRR) . 








| 5. The 256-byte storage area obtained by subroutine ILBOCVB is used 


by subroutine 




| ILBOOST. 










j 6. Because the ILB 


DODBG; subroutine dynamically loads and 


deletes su 


broutines as they 




| are needed, dep 


ending on the options specified, it is 


possible only to estimate a 




I minimum and/or 


a maximum amount of storage used by anj 


' one of the 


debugging 




| options. For each storage estimate given below, the effect of possible core 




| fragmentation i 


s not considered. 








I a. Basic debug 


package — 3768 bytes 








| b. Debug with 


the STATE option — 4640 bytes 








I c. Debug with 


the FLOW option — 5464 bytes 








I d. Debug with 


SYMDMP option — 14,000 bytes minimum and 20,000 bytes maximum. 




| 7. The subroutine 


or dynamic work area indicated as obtained conditionally. 




| 8. The subroutine 


indicated is never called as a primary 


subroutine. 






| 9. The subroutine 


indicated must be on-line at execution 


time. 






j 10. The subroutine 


indicated may reguire SYS1.TELCMLIB to 


be in-line 


at execution 




I time. 










1 11. The subroutine 


indicated is called explicitly by CALL 


statements 


in the COBOL 




I program. 











Figure 174. Calling and Storage Information for COBOL Library Subroutines (Part 7 of 7) 



Appendix B: COBOL Library Subroutine 489.1 



APPENDIX Ci FIELDS OF THE DATA CONTROL BLOCK 



In this appendix, eac 
control block is listed 
operand of the assembler 
instruction that can spe 
that field. Figures 175 
illustrate the data cont 
sequential, direct, rela 
files. Some of the data 
fields can be referred t 
parameter of the DD stat 
any field filled in by t 
cannot be overridden exc 
file OPTCD field in whic 
L-subparameter is set by 
DCB exit. 



h field of the data 
by the name of the 
-language macro 
cify a value for 

through 179 
rol blocks for 
tive, and indexed 

control block 
o with the DCB 
ement. However, 
he COBOL compiler 
ept for the indexed 
h the 

the compiler using 



Values for fields for which no entry 
appears in the column headed "COBOL Source" 
may be supplied by the DD statement or by 
the data set label. 

For information concerning the 
specification of values for data control 
block fields, see the DCB macro instruction 
for the different file processing 
techniques in the publication OS/VS Data 
Management ffacro I nstruction s . 



Note: The DCB subparameters are discussed 
under "User Defined Files" in the chapter 
"User File Processing." 
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(Block Field \ 


— ■" — - — — i 

Explanation of Field j 


— « 

COBOL Source 


l 

Applicable j 
DD Statement J 

DCB Sub parameters j 

« 


JBFALN 




Alignment 


(COBOL specifies double- 
word boundary) ] 


1 


JBFTEK 




Buffering technique 
(S or E) 


(COBOL specifies S) 




JBLKSIZE 




Maximum length of block 


BLOCK CONTAINS 

Data record description 


BLKSIZE J 


fBUFCB 




Address of buffer pool 


SANE AREA 




IBUFL 




Length of each buffer 






JBUFNO 




Number of buffers 
assigned to DCB 


RESERVE 


BUFN0=N(default=2) J 


IBUFOFF 








(BUFOFF=[nfl]) | 


{DDNARE 




Name of DD statement 


ASSIGN clause 




JDSORG 




Access method 


ASSIGN clause 
ACCESS clause 




IEODAD 




Address of user's end-of- 
data-set exit routine 
for input data set 


READ. ..AT END 




| EROPT ( 
I note) 


see 


Error option 




(ESOPT=[ ACCJSKP|ABE]) | 


JEXLST 




Address of exit list 


Used by the compiler for 
USE. ..LABEL, etc. 




ILRECL 




| Logical record length 


FD entry 


LRECL J 


IMACRF 




[Type of macro instruction 


OPEN INPUT, READ 
OPEN OUTPUT, WRITE 
OPEN 1-0, READ, WRITE 
REWRITE 




| OPT CD 




lOptional service provided 
by control program 


CODE-SET 


(0PTCD=[WJCJWC|TIQ3) | 


fRECFM 




I Characteristics of 
1 records in data set 


I RECORDING NODE 

| Record description 

ADVANCING 
| POSITIONING 
| BLOCK CONTAINS 
I APPLY RECORD-OVERFLOW 


(RECFM=D) J 


ISYNAD 
1 




| Address of error exit 
( routine 

i 


| Used by compiler for 
| INVALID KEY and 
| USE AFTER ERROR 

i . 


RECFM={SJT} | 

L , 1 


1 








1 


iNote: if th< 
|f or "the QSAH 
J never receive 


a COBOL program contains F. 

file, EROPT=ACC should be 

e control when certain abei 


CLE STATUS or USE AFTER Ell 
specified; otherwise, the 
rid situations arise. 


JOR/EXCEPTION clauses J 
COBOL program will | 



Figure 175. Data Control Block Fields for Physical Sequential Files (QSAM) 
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1— — — - \ 

J Data Control 
{Block Field 


r — _ , 

Explanation of Field 


i — \ 

COBOL Source 


I — 

Applicable 

DD Statement 

DCB subparameters 


IBLKSIZE 


Maximum length of block 


Data record description 




JDDNANE 


Name of DD statement 


ASSIGN clause 




JDSORG 


Access method 


ASSIGN clause 
ACCESS clause 




JEODAD 


Address of end-of-data-set 
exit (input) 


READ.. .AT END 




IEXLST 


Address of exit list 


USE. ..LABEL PROCEDURE 




JKEYLEN 


Length of key 


ACTUAL KEY* 
(length of 
ACTUAL KEY - 4) 




JLSECL 


Logical record length 


FD entry 


LRECL 


I H ACRF 


Type of macro instruction 


OPEN INPUT, READ 

OPEN OUTPUT, 

WRITE (DIRECT ONLY) 




IOPTCD 


Optional service to be 
provided by control 
program 




I I0PTCD=WJT] 


JRECFM 


Characteristics of 
records in data set 


RECORDING MODE 
Record description 
APPLY RECORD-OVERFLOW 




JSYNAD 


| Address of error exit 
I routine 


USE AFTER ERROR 
INVALID KEY 





I 1 Direct files only; for relative files, the field is 0. 

t , 



Figure 176. Data Control Block Fields for Direct and Relative Files Accessed 
Sequentially (BSAM) 
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|Data Control 
j Block Field ; 
1 


Explanation of Field 


COBOL Source 


Applicable 

DD Statement 

DCB Subparameters 


1BLKSIZE 


Maximum length of block 


Data record description 




|DDNAME 


Name of DD statement 


ASSIGN clause 




JDSORG 


Access method 


ASSIGN clause 
ACCESS clause 




IEXLST 


Address of exit list 


USE... LABEL, etc. 




|KEYLEN 


Length of key for each 
physical record 


ACTUAL KEY 1 
(length of 
ACTUAL KEY - 4) 




JLIHCT 


Search limits 




LIMCT=n (OPTCD=E 
must be specified) 


JMACRF 


Type of macro instruction 


OPEN INPUT, READ 

OPEN OUTPUT, 

HRITE (DIRECT ONLY) 1 

OPEN 1-0, READ, 

WHITE (DIRECT ONLY) , 

REWRITE 




IOPTCD 


Option service to be 

provided by the control 
program 




OPTCD=E/W 


IRECFM 


I Characteristics of 
1 records of data set 


RECORDING MODE 

APPLY RECORD-OVERFLOW 

Record description 




ISYNAD 


[Address of error exit 
| routine 


[Used by compiler for 

INVALID KEY and 
j USE AFTER ERROR 





|*Direct files only, for relative files this field is 0. 

i 



Figure 177. Data Control Block Fields for Direct and Relative Files Accessed Randomly 
(BDAM) 
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1 - — 1 

J Data Controli 
1 Block Field \ 


, 

Explanation of Field 


r — "" - — ■ — — i 

COBOL source j 


r _ 

Applicable 

DD Statement 

DCB Subparameters 


JBFALN 


Buffer alignment (F or D) 


(COBOL specifies D) 




JBKLSIZE 


Maximum length of block 


BLOCK CONTAINS 


BLKSIZE 


JBUFCB 


Address of buffer pool 


SAME AREA i 




1BUFNO 


Number of buffers assigned 
to DCB 


RESERVE 


BUFNO=N (def ault=2) 


jCYLOFL 


Number of overflow tracks 
for each cylinder 




CYLOFL=XX 


JDDNAME 


Name of DD statement 


ASSIGN clause 




JDSORG 


Access method 


ACCESS clause 
ASSIGN clause 




JEODAD 


Address of user's end-of- 
data-set exit routine 
for input data set 


READ... AT END 




JEXLST 


Address of exit list 


Used by the compiler j 




JKEYLEN 


Length of key for each 
logical record 


RECORD KEY 




JLRECL 


Logical record length 


FD entry 


LRECL 


IMACRF 


Type of macro instruction 


OPEN INPUT, READ, START 1 
OPEN OUTPUT, WRITE 
OPEN 1-0, READ, START, 
REWRITE 




JNTM 


Maximum number of 

cylinder index tracks 




NTM=XX 


JOPTCD 


Optional services 




OPTCD = UR|»J YJMJUJL 
{must also have 

NTfl=B) 


JRECFM 


Characteristics of 
records in data set 


RECORDING MODE 
RECORD DESCRIPTION 
BLOCK CONTAINS 




|RKP 


Relative position of 
record key in logical 
record 


RECORD KEY 




JSYNAD 


I Address of error exit 
routine 


i Used by the compiler for 

I INVALID KEY, 

| USE AFTER ERROR 





Figure 178. Data Control Block Fields for Indexed Sequential Files Accessed Sequentially 
(QISAM) 
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1 — — — 1 

(Data Control s 
| Block Field 

i 


Explanation of Field 


i — - — i 
COBOL Source 


Applicable f 

DD Statement j 

DCB Subparameters j 


1 i 
IBFALN | 


Buffer alignment (F or D) - j 


{COBOL specifies D) 




(DDNAHE 


Name of DD statement. 


ASSIGN clause 




IDSOFG 


Access method. 


ACCESS clause 
ASSIGN clause 




I EX L ST 


Address of exit list. 


Used by the compiler 




JKEYLEN 


Key length. 


NOMINAL KEY 




JLRECL 


Logical record length. 


FD entry 




IHACRF 


Type of macro instruction. 


OPEN INPOT, READ 
OPEN 1-0, READ, 
WRITE, REHRITE, 




JMSfll 


Address of area for 
highest level index 
of data set. 


APPLY CORE-INDEX 




IMSHA 


Address of area reserved 
I for control program. 
Required for variable 
length records. 


TRACK-AREA 




ISHSI 


ISize for area provided for 
I highest level index of 
1 the data set. 


IAPPLY CORE-INDEX 




JSHSW 


{Number of bytes reserved 

for main storage 
I work area. 


TRACK-AREA 





Figure 179. Data Control Block Fields for Indexed sequential Files Accessed Randomly 
(BISAM) 
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APPEN£II_li COMPILER OPTIMIZATION 



In general, compilation is faster when: 

1. Options in the EXEC statement are 
specified to: 

a. Make more main storage available 
(the SIZE option and the JCL 
EEGION parameter) 

b. Optimize the space available for 
buffers (the BUF option) 

c. Suppress output (the NOSOURCE, 
NODECK, NOLOAD, and the SUPMAP 
options, among others) 

d. Suppress object code if one or 
more E-level messages are 
generated (CSYNTAX option) . 

2. The maximum block size for a compiler 
data set is specified. 

3. A disk configuration and separate 
channels for utility data sets are 
used. 

4. Separate devices (i.e., not the same 
mass storage unit) on the same channel 
are used. 

Compilation time is also affected by the 
speed of the devices allocated to the data 
sets. For example, a tape device is faster 
than a printer for printed output. The 
blocking information that follows applies 
to 0S/VS1 or 0S/VS2. 



• Specification of the COBOL Library 
Management Facility, via the RESIDENT 
compiler option, results in a saving of 
both main storage and secondary 
storage, as well as of time at the 
link-edit step and the initial program 
load for the program. 

» Dynamic invocation and release of COBOL 
subprograms, specified by the DYNAM 
compiler option, also results in 
savings in main storage. 

• A syntax checking compilation, 
specified by the SYNTAX or CSYNTAX 
compiler option, saves machine time. 
Depending on which compiler options are 
chosen, as well as the various source 
program statements, compile time can be 
reduced greatly. 



The symbolic dump featu 
the SYMDMP option, and sou 
debugging through USE FOE 
declaratives, can save muc 
However, use of either of 
can decrease performance e 
programs run with it. Tha 
programs reguire additiona 
compile, link-edit, and ex 
They also reguire more mai 
programs run without this 



re, specified by 

rce-level 

DEBUGGING 

h debugging time, 

these features 

xpectations for 

t is, such 

1 time for the 

ecute job steps. 

n storage than 

feature. 



For information about reguesting any of 
these options, see the section "Options for 
the Compiler" in the chapter on "Job 
Control Procedures". For information about 
USE FOB DEBUGGING, see the chapter "Program 
Checkout," 



PEHFORMANCE CONSIDERATIONS 



BLOCK SIZE FOR COMPILER DATA SETS 



The OS/TS COBOL Compi 
additional opportunities 
main storage or time. F 
specification of the Opt 
Feature, the COBOL Libra 
Feature, the Dynamic Sub 
all three of these featu 
a considerable saving in 
notes given below provid 
performance information 
with these and other new 



ler, provides 

for saving either 
or example, 
iraized Code 
ry Management 
program Feature, or 
res, can result in 

main storage. The 
e additional 
on programs run 

features. 



When the Optimized Code Feature is 
reguested, via the OPTIMIZE compiler 
option, execution time is reduced for 
no n- I/O bound programs; however, 
compilation time is increased. 



The blocking factor specified for 
compiler data sets other than utility data 
sets must be permissible for the device the 
data set is on. In addition, for the 
SYSLIN data set, it must be permissible for 
the linkage editor used. (Any block size 
specified for a utility data set in a DD 
statement is overridden by the compiler.) 
If a block size other than the default 
option is needed, it can be reguested by 
specifying the BLKSIZE subparameter of the 
DCB parameter in the DD statement for the 
data sets. The format of the subparamete 
is: 

DCB= (BLKSIZE=nnn) 
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where nnn is equal to N times the logical 
record size in bytes, and 1 < N < M. M is 
equal to the blocking factor permissible 
for the device, and, in the case of SYSLIN, 
to the blocking factor permissible for the 
linkage editor used. 

If blocking is desired, the record 
format for SYSPRINT [ DCB=(RECFM=nnn) ] 
should be specified as FBA. The record 
format for SYSIN, SYSLIN, SYSPUNCH, and 
SYSLIB should be specified as FB. 



jgote: For queued sequen 
RECFH subparameter of th 
optionally be specified 
permitting the programme 
standard block option (f 
recording mode F) or the 
option for the data set. 
overflow option is equiv 
APPLY RECORD-OVERFLOW cl 
program.) Use of the st 
(particularly for direct 
having the Rotational Po 
feature) results in the 
performance improvement. 



tial data sets, the 
e DD statement may 
at object time, 
r to specify the 
or data sets with 
track overflow 
(The track 
alent to writing an 
ause in the source 
andard block option 
-access devices 
sitional sensing 
significant I/O 



Fixed-block single volume data sets as 
created by COBOL are standard (except 
possibly when extended using the DISP=MOD 
parameter of the DD statement) . 
Hultivolume data sets as created by COBOL 
are standard if the volume switching occurs 
through automatic end-of-volume procedures. 
If, however, the programmer issues a CLOSE 
REEL/UNIT statement, then he must ensure 
that the number of logical records in the 
volume is an integral multiple of n, where 
a BLOCK CONTAINS n RECORDS clause (or an 
equivalent BLOCK CONTAINS CHARACTERS 
clause) has been specified in the source 
program. The standard block option and the 
track overflow option are mutually 
exclusive. 

The logical record size for SYSPRINT and 
SYS0T6 is 121 bytes. The logical record 
size for SYSIN, SYSLIN, SYSPUNCH, and 
SYSLIB is 80 bytes. 

Note: For compile, link-edit, and execute 
cases when labeled volumes are used, RECFH 
and BLKSIZE must be given for SYSLIN in the 
compile step only. If BLKSIZE is specified 
for SYSPUNCH, LRECL must also be specified. 



HOI BUFFER SPACE IS ALLOCATED TO BUFFERS 



Once the amount of space available for a 
compilation is determined, the compiler 
subtracts the amount required for itself. 
From the space remaining, it then computes 
the space available for utility and 
input/output data set buffers. If space 



still remains, the compiler makes use of it 
for internal processing. 



once the amount of space available for 
buffers is determined, the compiler 
calculates how this space is to be divided. 
First, it computes the amount of space 
required for the buffers of the 
input/output data sets. From the space 
remaining, it determines the maximum buffer 
size, and hence block size, possible for a 
utility data set. The four required 
utility data sets SYSUT1 through SYSUT4 all 
have the same block size. Thus, the block 
size of a utility data set is dependent on 
the amount of space available for buffers. 
If a block size has been specified in a DD 
statement for a utility data set, it is 
overridden. 

A larger buffer size for a utility data 
set allows for faster processing. However, 
if the program being compiled takes up a 
large amount of the available storage, a 
smaller space for buffers enables the 
compiler to use more main storage for 
internal processing. 

The following describes how the space 
available for buffers is determined and how 
it is allocated to buffers. 

Let A represent the total space that can 
be allocated to these buffers. It is 
determined as follows: 



1. If neither the BOF nor the SIZE option 
of the PARH parameter of the EXEC 
statement is specified, A equals the 
default value for buffer space. This 
value is specified at system 
generation time. The minimum value is 
4096 bytes. 

2. If the SIZE option is specified, but 
BOF is not, A equals (SIZE - 96K) / 4 
plus the default value for buffer 
space. 

3. If BUF is specified (whether or not 
SIZE is specified) , A eguals the value 
specified for BUF. 

Note: The minimum difference between 
SIZE and BUF must always be equal to 
or greater than the difference between 
the minimum SIZE value and the minimum 
BUF value (131,072 bytes - 12,288 
bytes) . 

4. If BUF is smaller than 4096 a warning 
message is printed and the minimum 
value is assumed. If BUF is too large 
to allow minimum table space for 
compilation, a warning message is 
printed and the default value (or the 
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minimum value, if the default value is 
also too large) is assumed. 



The programmer must make sure that the 
amount of buffer space allocated by the 
system is sufficient, taking into consid- 
eration the block sizes specified for the 
compiler data sets. The allocated buffer 
space is divided as follows: 

1. Let B represent the amount of buffer 
space to be allocated for input/output 
data sets. B is computed as either 
egual to: 

2 times the block size of SYSPRINT + 
SYSIN ♦ SYSLIB 



2 times the block size of SYSPRINT ♦ 
SYSPUNCH + SYSLIN 

whichever is larger. The maximum 
allowable value of B is A - 1280 bytes 
(1280 bytes less than the total buffer 
size) . If the computed value is 
greater than the maximum allowable 
value, a diagnostic message is printed 
and compilation is abandoned. 

Note: When the BATCH option is in 
effect, an additional SYSIN buffer 
is required. The first formula above 
then becomes: 

2 times the block size of 
SYSPRINT + SYSIN + SYSIN + 
SYSLIB 

If the block sizes are not 
specified in the DD statements, the 
following default values are assumed: 





Default 


Data „ Set 


Value (bytes) 


SYSIN 


80 


SYSLIN 


80 


SYSPUNCH 


80 


SYSLIB 


80 


SYSPEINT/SYS0T6 


121 or 133 


SYSTEBM 


121 


SYS UTS 


512 



N.otes: The default for SYSPEINT/SYSUT6 is 
133 if the L132 option is in effect. The 
512-byte block size for SYSUT5 cannot be 
overridden. 



2. Let C represent the amount of buffer 
space to be allocated for each utility 
data set. Therefore, C equals the 
block size of data sets, SYSUT1, 
SYSUT2, SYSUT3, and SYSUT4, 
respectively. 



A - B 



If A < 6B, then C - 



If A > 6B, then C = - 

6 



If C > maximum block size permitted 
for any device a utility data set is 
on, then the maximum block size is the 
value chosen for C. The minimum block 
size for SYS0T1 , SYS0T2, SYSUT3, and 
SYSUT4 is 256 bytes. 
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APPENDIX Ei IHV OCATIOH O F THE COBOL ,. COMPILER. ftHD COBOL COMPILED PROGRAMS 



The COBOL compiler can be invoked by a 
problem program at execution tine through 
the use of the ATTACH or the LINK macro 
instruction, i.e., dynamic invocation. 
Dynamic invocation of COBOL compiled 
programs can be accomplished through the 
use of the LINK, ATTACH, or LOAD macro 
instruction. 



INVOKING THE COBOL COMPILER 



The problem program must supply the 
following information to the COBOL 
compiler: 

• The options to be specified for the 
compilation 

• The ddnames of the data sets to be used 
during processing by the COBOL compiler 

• The header to appear on each page of 
the listing 



I Name 



-t r 

| Operation! Operand 



|[ symbol]! LIHK 
| | ATTACH 



-| 

JEP=IKFCBL00, 

J PARAM= (optionlist 

! [ , ddnamelist ], 

! [,headerlist]) ,VL=1 



where: 



EP 



specifies the symbolic name of the 
COBOL compiler. The entry point at 
which execution is to begin is 
determined by the control program 
(from the library directory entry). 



PARAH 



specifies, as a 
parameters to b 
problem program 
The first full* 
parameter list 
the COBOL optio 
fullword contai 
ddname list. I 
to be used and 
specified, this 
If standard ddn 
a header list i 
should contain 
half word of bin 
halfword. The 
the address of 
list may be omi 



sublist, address 
e passed from the 

to the COBOL compiler, 
ord in the address 
contains the address of 
n list. The second 
ns the address of 
f standard ddnames are 
no header list is 

list may be omitted, 
ames are to be used and 
s specified, this entry 
the address of a 
ary zeros, aligned on a 
last fullword contains 
the header list. This 
tted. 



option list 

specifies the address of a variable 
length list containing the COBOL 
options specified for compilation. 
For additional details, see the 
description of the EXEC statement in 
the chapter "Job Control Procedures." 
This address must be written even 
though no list is provided. 

The option list must begin on a 
halfword boundary. The two high-order 
bytes contain a count of the number of 
bytes in the remainder of the list. 
If no options are specified, the count 
must be zero. The option list is free 
form with each field separated from 
the next by a comma. No blanks or 
zeros should appear in the list. 

ddname list 

specifies the address of a variable 
length list containing alternative 
ddnames for the data sets used during 
COBOL compiler processing. If 
standard ddnames are used, this 
operand may be omitted. 

The ddname list must begin on a 
halfword boundary. The two high-order 
bytes contain a count of the number of 
bytes in the remainder of the list. 
Each name of less than eight bytes 
must be left justified and padded with 
blanks. If an alternate ddname is 
omitted from the list, the standard 
name will be assumed. If the name is 
omitted within the list, the 8-byte 
entry must contain binary zeros. 
Names can be omitted from the end 
merely by shortening the list. 

All utility data sets passed to the 
compiler must be physical seguential 
(for example, DSORG=PS must be their 
type of organization) . 

The sequence of the 8-byte entries in 
the ddname list is as follows: 



ddname 


Name for 


8-byte 


Entry 


Which Substituted 


1 




SYSLIN 


2 




not applicable 


3 




not applicable 


4 




SYSLIB 


5 




SYSIN 


6 




SYSPRINT 


7 




SYSPUNCH 


8 




SYSUT1 


9 




SYS0T2 


10 




SYS0T3 
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11 

12 
13 
14 



SYSUT4 
SYSTERH 
SYSUT5 
SYSUT6 



When the COBOL compiler completes 
processing, a return code is placed in 
register 15. For additional details, see 
the discussion of the COND parameter in the 
chapter "Job Control Procedures. M 



header list 

specifies the address of a 
variable-length list containing 
information to be included in the 
heading on each page of the listing. 
The list must begin on a ha If word 
boundary. The two high-order bytes 
should contain a 4 (the count of the 
number of bytes in the new heading 
information). The next four bytes of 
the list should contain the page 
number at which the heading is to 
start, in EBCDIC format. 



INVOKING COBOL COMPILED P80GRAMS 



Linkage editor control cards should be 
specified as follows: 

1. For the PROGRAM-ID program-name, a 
NAME card. 

2. For each ENTRY literal- 1, an ALIAS 
card should be specified in a COBOL 
program that is to be dynamically 
invoked. 



VL 



specifies that the sign bit is to be 
set to 1 in the last fullword of the 
address parameter list. 
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APPENDIX F: SOURCE PROGRAM SIZE CONSIDERATIONS 



This appendix contains information to 
aid the programmer in determining how his 
source program affects usage of space at 
compilation time and linkage editing time. 



COMPILER CAPACITY 



The capacity of the COBOL compiler is 
limited by two general conditions: (1) the 
total space available must be sufficient 
for compilation and (2) an individual table 
may not have a length greater than 32,767 
bytes, with the exception of the ADCON and 
cross-reference tables. If either of these 
conditions is not met during compilation, 
one of the following error messages will be 
issued: 



IKF0001I-D SIZE PARAMETER TOO SMALL FOR 
THIS PROGRAM. 

IKF0010I-D A TABLE HAS EXCEEDED THE MAXIMUM 
PERMISSIBLE SIZE. 

In either case, compilation is terminated. 
However, in the first case, the program may 
be recompiled with a larger SIZE parameter. 
The size of the ADCON and cross-reference 
tables is not limited to 32,767 bytes. 

If a table overflows, the following error 
message will be generated, and the user 
will need to rerun the program in a larger 
region. 

IKF6007I-D TABLE OVERFLOW. PflAP LOAD 
MODULE OR DECK WILL BE 
INCOMPLETE. INCREASE SIZE 
PARAMETER. 



Minimum Conf i guration SOURC E PROGRA t}„size 



The compiler will accept and compile a 
2000 card program in its minimum main 
storage allocation (128K). Of course, the 
various reader procedures may affect the 
value required for SIZE and BUF parameters. 
The compiler will allocate the minimum 
required amounts that are 256 bytes for 
each of the 4 intermediate files, 80 bytes 
for each system file with the exception of 
SYSPRINT for which 121 or 133 bytes are 
allocated. Double buffering will be 
assumed. 



EFFECTIVE STORAGE CONSIDERATIONS 



The amount of main storage within the 
compiler's partition and the limitation on 
the size of an individual internal table 
are two factors that limit the capacity of 
the compiler. The limitation on the size 
of internal tables can, in some instances, 
be overcome by the spilling over of some 
tables onto external devices. However, 
spilling over may cause a severe 
degradation of performance. The main 
storage limitation should not be reached by 
any reasonable use of the language. 
However, within a limited storage capacity 
excessive use of certain features and 
combination of features in the language 
could make compilation impossible. Some of 
the features that significantly affect 
storage usage are the following: 

1. Text Punch Table 

Each entry occupies 8 bytes. This 
table is not limited to the maximum 
size of 32,767 bytes. Entries are 
based on the: 

• Number of 4096-byte segments in the 
Working-Storage Section 

• Number of 4096-byte segments in a 
file buffer area 

• Number of referenced procedure- names 

• Number of implicit procedure-name 
references such as those generated 
by IF, SEARCH, and GENERATE 
statements, ON SIZE ERROR, ON 
OVERFLOW, INVALID KEY, and AT END 
options, the OCCURS clause with the 
DEPENDING ON option, USE sentences, 
and the Segmentation feature. 

• Number of files 



Procedure7-name_Table 

This table contain 
definitions written i 
unresolved procedure 
procedure references 
the end of a section 
of the procedure-name 
section or a precedin 
Therefore, forward re 
section impact space. 
900 ungualified entri 
A maximum number of 1 
be specified. 



s the number of 
n a section and 
references, 
are resolved at 
if the definition 

is in that 
g section, 
ferences beyond a 

Approximately 
es are possible. 
6,255 entries may 



Appendix F: Source Program Size Considerations 501 



OCCURS DEPENDING OH Table 

This table contains an entry for 
each unique object of an OCCURS clause 
with the DEPENDING ON option. The 
size of an entry is 2 ♦ length of name 
♦ length of each gualifier bytes. 



An entry is made for each INDEXED 
BY clause consisting of 11. bytes for 
each index. 



• SAME [RECORD] AREA clause 

• Subscripting 

• Intermediate Arithmetic Results 

• Complex Arithmetic Expressions 

• Complex Logical Expressions 

• APPLY clauses 

• Special-Names 

• RERUN clauses 

• Error messages 

• XREF 

• Segmentation feature 

• USE FOE DEBUGGING 



File Table 



An entry is made for each file 
specified in the program. Each entry 
occupies 60 bytes of storage. 

6 - Report Writ er Table s 



A considerab 
information is 
such as control 
footings, routi 
and so on. The 
are increased b 
subscripting in 
Approximately 3 
processed witho 
of the table. 



le amount of 
maintained for each RD 
s, sums, headings, 
nes to be generated, 

contents of the table 
y qualification and 

the Report Section. 
reports can be 
ut exceeding the limit 



Dictionar y Table 

An entry is made for each 
procedure-name and each data-name in 
the program. A procedure entry 
consists of (7 or 9 ♦ length of name) 
bytes. A data entry consists of 
{length of name * n) bytes, where n is 
determined by the attributes of the 
data item. Some of the features that 
contribute to the value n are: 



LINKAGE EDITOR CAPACITY 



Some COBOL program and linkage editor 
considerations are listed below as a 
further guide in preparing a source 
program. Consult the publication Q S^VS 
Linkage Editor and Loader, for additional 
information on linkage editor capacities 
and processing. 

1. All COBOL object programs consist of a 
single CSECT (control section) . The 
size of the object module may be 
determined by looking at the location 
of the last instruction in INIT3 in 
the object code listing (see the 
section entitled "output") or from the 
END card. 

2. The size of the object module is 
greatly increased by any of the 
following: 

a. The blocking factor and alternate 
area reservation of randomly 
accessed files 



• One byte for each character in a 
numeric edited or alphanumeric 
edited item picture 

• Five bytes for an elementary item 
with a Sterling Report picture 
clause 

• Three bytes for an item subordinate 
to an OCCURS clause 

8 - L it e ral Tables 

The total length of all literals 
may not exceed 3251 1 bytes. No more 
than 16255 literals may be specified. 

9 • Miscellaneous Table s 

The presence of the following items 
causes entries to be made into tables 
that affect the total space required 
for compilation. 



b. The specification of the SAME AREA 
clause for sequentially accessed 
files 

3. RLD (Relocation List Dictionary) cards 
are part of the load module, and are 
used by the linkage editor to compute 
the address constants for the load 
module. The number of RLDs produced 
by the compiler can be determined by 
the following formula: 

number of RLDs = number of unique 

subprograms called ♦ number of COBOL 
library routines called 

4. The output text of the compiler is 
written out in a sequence that differs 
from the order indicated by the 
location counters contained in each 
output item. This sequence difference 
may result in a strain on the 
facilities of the linkage editor. 
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5. VALUE clauses in the Working-Storage 
Section nay result in many 
discontinuous text records. 

6- The object aodule produced by the 
COBOL coapiler will not be in 
ascending address by card order prior 
to the linkage editor step. 
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APPENDIX GZ INPUT /OUTPUT ER ROR CONDITIONS 



This appendix consists of tiro sections, 
each describing detailed information 
available to the programmer after an 
input/output error: 

S ection 1 is a sample listing of the 
possible contents of certain fields within 
data-name- 1 of the error declaratives 
GIVING clause. This listing is presented 
as a guide for the programmer in analyzing 
his own program at the COBOL source level. 

Section 2 describes pertinent 
input/output error conditions according to 
access method, including guidance in the 
use of the INVALID KEY and error 
declarative features. 



Note: More detailed information for use in 
diagnosing error conditions may be found in 
Q§/yS-,^Sta,3^.nMgggPt: J ..!9a i <?¥o..X]!?}?t ruptioas 
and in either QS / VS1 System D ata Areas , 
Order No. SY28-0605~or OS/VSSTsystem Data 
Areas, Order No. ST68-0606 TRelease 1) or 
SYBS-0606 (Release 2 or later) . 

Sec tion 1 

Figure 180 is a sample listing of a 
constant area within one of the modules 
used in SYNADAF processing to formulate the 
descriptive error message ultimately 
reported to the programmer in data-name- 1 
of the error declarative GIVING option. 
Part 1 of the table is used to fill in 
the 6-byte field referred to as 
OPERATION-ATTEMPTED, bytes 85-90 of 
data-name- 1. Part 2 is the source of the 
6-byte field known as ACCESS-METHOD. Bytes 
108-128 contain this field, the exact six 
bytes depending on the device type — unit 
record, magnetic tape, mass storage. 

Note: COBOL supports only QSAM, BSAM, 
BDAM, BISAM, QISAM and VSAM at the source 
level. 

Part 3 of the table provides the 
contents of the most important field, the 
15-byte ERROR-DESCRIPTION, bytes 92-106. 
Parts 1 and 3 are arranged by access 
method, in general, and a nuaber of entries 
in one part are repeated in the other. 



The programmer may use this listing as a 
guide to determining the nature of his 
error within the declarative by examining 
the appropriate fields. By analyzing these 
fields with the aid of Section 2 of this 
appendix, the programmer can determine what 
are the conseguences of the error and what 
can be done about it. 



Important: First, if either the 
OPERATION- ATTEMPTED or ERROR-DESCRIPTION 
field specifies "unknown" in some way, the 
contents of data-naae-2 are probably 
invalid, as described in "Error Processing 
for COBOL Files" earlier in this 
publication. Referencing data-narae-2 in 
this situation should not be done since it 
may cause an abend. 

Second, the module which contains data 
similar to Figure 180 is part of the 
operating system and, as such, is subject 
to possible modification with each new 
release — including insertion or deletion 
of fields, modification of descriptions, 
and so forth. In order to ascertain the 
contents of this constant area in use at a 
particular installation, the programmer may 
consult the microfiche listing of the 
modules. 

The following modules issue SYNADAF 
messages in bytes 92 to 106 of the message 
buffer: 

IGC0106H 
IGC0206H 
IGC03 06H 
IGC0406H 
IGC0606H 
IGC0706H 
IGC0806H 
IGC09 06H 

The contents of actual messages issued can 
be found by consulting the microfiche for 
these modules. 

If microfiche listings are not 
available, the sample job in Figure 181 may 
be executed to get a dump of the 
appropriate module; the fields described 
above- may then be extracted from this dump. 



SOU 



* 
* 
DMLIST1 



DMLIST2 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 



QSAMS 

BSAMS 

BPAMS 

BDAMS 

BISAMS 

QISAMS 

BTAMS 

QTAMS 

GAMS 

ERRORS 



UNKNOWN 

FCBLST 
EXTENT 

PURGED 
ERRLIST 



ERROR1 



ERROR2 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 



SYNAD_ANALYZE AND FORMAT SVC * 

INITIAL LOAD * 

READ » FILL IN FOB TYPE OF OPERATION 

WRITE » 
C NT-OP* 



POINT 

UNKN' 

GET 

PUT 

UNKN' 

UNKN' 

SETL* 



POINT OPERATION 
UNKNOWN OPERATION 



ACCESS METHOD TYPES 



QSAM 

BSAM 

BPAM 

BDAM 

BIS AM 

QISAM 

BTAM 

QTAM 

GAM 



FOR EXCP, BPAM, BSAM, 



DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
SPACE 1 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 

DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
SC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 
DC CL15 



CHAN CTL CK« 
INTF CTL CK* 
PROG CHECK' 
PROT CHECK* 
CHAIN CHECK* 
UNKNOWN COND. ' 
END OF FILE* 
WRNG.LEN. RECORD* 
UNKNOWN COND.* 



NO ERROR STATUS* 
OUT OF EXTENT* 
PREV D. E. ERROR* 
PURGED REQUEST* 
R.HA.RO - ERROR* 

FOR BDAM AND BIS AM 
RECORD NOT FND • 
RECD LGTH CHECK* 
NO SPACE AVAILB* 
INVALID REQUEST* 
UNCOR I/O ERROR* 
UNHEACHBLE BLCK • 
OVERFLOW RECORD* 
DUPLICATE RECRD* 
NOT IN SRCH.LMT* 
WRNG.LEN. RECORD* 
SPACE NOT FOUND* 
INVALID REQUEST* 

I/O ERROR » 

END OF DATA » 
ERROR NOT I/O » 
EXCLUSIVE CNTRL* 

INPUT DCB » 

LIMCT=0-EX.SRCH» 

OUT OF EXTENT * 

CAPACITY RECORD* 



QSAM, AND BDAM 
ERROR MESSAGES 



0140001 
0180001 
6720001 
6740001 
6760001 
6780001 
6800001 
6820001 
6840001 
6860001 
6880001 
6900001 
6920001 
6940001 
6960001 
6980001 
7000001 
7020001 
7040001 
7060001 
7080001 
7100001 
0330001 
7320001 
7350001 
7380001 
7410001 
7440001 
7470001 
7500001 
7530001 
7560001 
8130001 
8160001 
8190001 
8220001 
8250001 
8280001 
0330001 
5490001 
5520001 
5550001 
5580001 
5610001 
5640001 
5670001 
5700001 
6300001 
6330001 
6360001 
6390001 
6420001 
6450001 
6480001 
6510001 
6570001 
6600001 
6630001 
6660001 



Figure 180. Sample Constant Area Used in SYHADAF Processing (Part 1 of 3) 
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* 

NOTAPI 

UNKNOWN 

COND1 

EXTENTS 



* 

UNKNOWN 
UCKEES 



DC 
DC 
DC 
DC 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 



CL15* INCORBBCT KEY • 
CL15« INVALID OPTIONS 1 
CL15'FIX.LEN.KEY'*F* " 
CL15' UNKNOWN ERROR * 

SECONDARY LOAD 
FOR QISAM 
CL14»NOT APPLICABLE' 
CL15' UNKNOWN COND. • 
CL15»KEY NOT FOUND • 
CL15' OUT OF EXTENT ' 
CL15*SPACE NOT FOUND* 
CL15*INVALID REQUEST 1 
CL 15* SEQUENCE CHECK • 
CL15»DUPLICATE RECRD* 

SYNAD ANALYZE AND FORMAT SVC 
UNIT CHECK ANALYSIS 
FOR EXCP, BPAM, BSAH, QSAM, AND BDAM 



DUM 



******* 

* 

* 

* 



DC 
DC 
DC 
DC 
DC 
DC 
DC 

MY IT 
DC- 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 

***** 



CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 



EM INSERTED TO INSURE PROPER MSG FIELD 



CL15 
CL15 
CL15 
CL 15 
C1 15 
CL15 
C1 15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 



UNKNOWN COND. 

PQP CHECK* 

BUS OUT CK» 
CMD REJECT* 
INT REQ * 

DATA CHECK* 

OVER RUN' 



MICS 



UNKNOWN DUMMY 
LATE STKR SEL* 

TRACK COND CK» 

WORD COUNT ZERO' 

INV CMD SEQ* 
POSITION CK' 

SEEK CHECK* 

DATA C. CHECK 1 
OPERATOR ATTN* 

TRACK OVERRUN* 

CYL END « 

INVALID SEQ* 

NO REC FOUND* 

FILE PHOT* 

MISSING A.M.* 

OVRF INCP* 

UNKNOWN COND. « 



HICR 14 19/1275 SCU 



TCR 



MICE 



S19033 



S19033 
SI 9033 



S19033 



S19033 



6690001 
6720001 
6750001 
6780001 
0360001 
0440001 
7280001 
7320001 
7680001 
7720001 
7760001 
7800001 
7840001 
7880001 
0210001 
0270001 
0330001 
7560001 
7590001 
7620001 
7650001 
7660001 
7680001 
7710001 
7717001 
7724001 
7731001 
7740001 
7770001 
7800001 
7810001 
7830001 
7860001 
7870001 
7890001 
7920001 
7950001 
7980001 
8010001 
8040001 
8070001 
8100001 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 



************************************************* 
SYNAD ANALYZE AND FORMAT SVC 
ADDITIONAL SECONDARY LOAD 
FOR QISAM, BTAM, AND GAM 



CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 
CL15 



CHAN CTL CK' 
INTF CTL CK' 
PROG CHECK' 
PROT CHECK' 
CHAIN CHECK' 
UNKNOWN COND. ' 
END OF FILE' 
WRNG.LEN. RECORD* 
UNKNOWN COND.' 
EQP CHECK' 
BUS OUT CK» 

CMD REJECT* 
DATA CHECK* 



Figure 180. Sample Constant Area Used in SYNADAF Processing (Part 2 of 3) 
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DC CL15«DATA CHECK* 

DC CL15*0VER RUN' 

DC CL15»TRACK COND CK* 

DC CL15*WORD COUNT ZERO* 

DC CL15*INV CMD SEQ» 

DC CL15»SEEK CHECK* 

DC CL15*DATA C.CHECK* 

DC CL15'TRACK OVFL* 

DC CL15*CYL END * 

DC CL15»INVALID SEQ* 

DC CL15'NO REC FOUND* 

DC CL15*FILE PROT* 

DC CL1S»MISSING A.H.* 

DC CL15*OVE8FL INCP* 

DC CL15*UNKNO»N COND. » 



Figure 180, Sample Constant Area Used in SYNADAF Processing (Part 3 of 3) 



//IGC0106H 


JOB 


ACCTING-INFO 


//ZAPSTEP1 


EXEC 


PGH=IMASPZAP 


//SYSLIB 


DD 


DSN=SYS1.SVCLIB,DISP=OLD 


//SYSPRINT 


DD 


SYSOUT=A 


//SYSIN 


DD 


* 


DIIMPT 


IGC0106H 


ALL 



/* 

Note: The DSN shown is for VS1; for VS2 
the DSN sould be SYS1.LPALIB 

Figure 181. A Sample Job to get a Dump of a Constant Area 
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Section 2 



An INVALID KEY condition can usually be 
remedied by merely changing the key and 
trying the operation again. This technique 
of altering the key can be used, on a READ, 
to determine if a record with a particular 
key already exists in a file; this aay be 
regarded as a test to determine the flow of 
logic for a particular update operation. 

An input/output error condition is 
usually not easily remedied, and quite 
often the only operation possible is to 
close the file. 

The following corrective actions are 
presented according to access method and 
further broken down according to error 
condition. If VSAM (Virtual storage Access 
Method) is being used, see "Error 
Processing Options'* and "Status Key 
Settings for Action Requests" in the 
chapter "VSAM File Processing". 



iQSAM ( p hysical seque ntial). 



INVALID KEY Condition : 

• SPACE NOT FOUND. For a file opened as 
OUTPUT, no more space exists to contain 
another record. Processing is limited 
to a CLOSE, but the file may be further 
processed as INPUT or 1-0. 



In put/Output Error Condition s : 

• INPUT ERROR. 

• OUTPUT ERROR. 

For these two conditions, the user aay 
return to the system from the 
declarative, thus executing the 
processing option (EROPT) specified on 
his DD card: 

1. ABE (default) — terminate the step 
with an abend. 

2. SKP — skip to the next block. 

3. ACC — accept the block in error 
and continue processing. 

i 1 

I OISAH (indexed sequential), J 

1 — : ZZ 1 

INVALID KEY Conditions : 

• LOWER KEY LIBIT NOT FOUND. The value 
specified for NOMINAL KEY before a 
START statement does not have a match 



in the file. Processing may be 
continued. 

SEQUENCE CHECK. For a file opened 
OUTPUT, an attempt was made to add a 
record whose RECORD KEY was not greater 
than that of the last record added. 
Processing may be continued. 

DUPLICATE RECORD. An attempt was made 
to add a record to a file whose RECORD 
KEY was already present in the file. 
Processing may be continued. 



Input/Ou tput Error Condit ions : 

• SPACE NOT FOUND. No space was 
available in the currently accessible 
prime area to add the record. Current 
OUTPUT processing is limited to a 
CLOSE. 

• UNREACHABLE BLOCK (INPUT OR I-O) . 

• UNCORRECTABLE OUTPUT ERROR. 

For these last two conditions, the user 
can attempt the operation again; 
possibly the problem is transient. If 
the error persists, processing is 
limited to a CLOSE. 

• UNCORRECTABLE INPUT ERROR. The user 
can attempt to bypass the block in 
error by executing sufficient READ 
operations to force the next block into 
main storage. If the error does not 
persist on the next block, processing 
may be continued; otherwise it is 
limited to a CLOSE. 



BISAM (indexed ran dom ) 



IN VA LI D_ KE X_Co ndi t io n s : 

• RECORD NOT FOUND. The record 

corresponding to the value of NOMINAL 
KEY or READ was not found in the file. 
Processing may be continued. 

« DUPLICATE RECORD, An attempt was made 
to add a record with a key which 
already exists in the file. Processing 
may be continued. 



Input/Outp ut error C ond it ions : 

• SPACE NOT FOUND. No space was 

available in the currently accessible 
prime or overflow area to add the 
record. Depending on the physical 
makeup of the file, adds for other keys 
may be possible. Processing may be 
continued. 
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• INVALID REQUEST. A logic error in the 
source program exists: for example, an 
attempt to REWRITE a record for which 
no valid READ was done. Processing is 
limited to a CLOSE. 



length record whose ACTUAL KEY has 
HIGH-VALUE in the first byte of its 
symbolic portion. Processing may 
be continued. 



• UNCORRECTABLE INPUT/OUTPUT ERROR. 

• UNREACHABLE BLOCK (INDEX CANNOT BE 
READ). 

For these last two conditions, the user 
can attempt the operation again; 
possibly the problem is transient. If 
the error persists, processing is 
limited to a CLOSE. 



I B DAH { d irect an d relative f random ) | 

i 1 

INVALID KEY Conditions : 

• RECORD NOT FOUND. A record 
corresponding to the value of the key 
was not found in the file. Processing 
may be continued. 

• END-OF-DATA RECORD READ. The 
end-of-data set indicator has been read 
as a result of the value of the ACTUAL 
or NOMINAL KEY. This is really an 
indication that the value of the key is 
outside the limits of the data set. 
Processing may be continued. It must 
be emphasized that this is an extremely 
rare occurrence. 

• INVALID REQUEST. This may be caused by 
two separate conditions: 

1. BLOCK OUTSIDE LIMITS OF DATA SET. 
The value of the ACTUAL or NOMINAL 
KEY was found to reference a disk 
address outside the space occupied 
by the data set. Processing may be 
continued. 

2. FIXED LENGTH KEY WITH X'FF*. An 
attempt was made to add a fixed 



Input/Output Error Conditions : 



• SPACE NOT FOUND. An attempt has been 
made to add a record to the data set, 
and all space allocated to the data set 
has been filled. No further WRITE to 
the data set can be executed, but 
processing may be continued. 

• UNCORRECTABLE ERROR, 1-0 OR NON-1-0. 
Processing is limited to a CLOSE. 



I BSAM (direct and relati ve, 

i 



sequential) J 



INVALID KEY Condition : 

• SPACE NOT FOUND. For a file opened as 
OUTPUT, no more space exists to add a 
record. Processing is limited to a 
CLOSE, but the file may be further 
processed as INPUT or 1-0. 



Input/Output E rror Conditions : 

• INVALID REQUEST. A logic error in the 
source program exists: for example, an 
attempt to REWRITE a record for which 
no valid READ was done. Processing is 
limited to a CLOSE. 

• INPUT ERROR. 

• OUTPUT ERROR. 

For these last two conditions, the user 
can attempt the operation again; 
possibly the error is transient. If 
the error persists, processing is 
limited to a CLOSE. 
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APPEN2H-HJ CHEATIN G AN D RETRIEVING INDEXED SEQUENTIAL DATA SETS 



Indexed data sets (ISAM) are created and 
retrieved using special subsets of DD 
statement parameters and sub para meters. 
They can occupy up to three different areas 
of space: 

• Prime Area — This area contains data 
records and related track indexes, it 
exists for all indexed data sets. 

• Overflow Area — This area contains 
overflow from the prime area when new 
data records are added. It is 
optional. 

• Index Area — This area contains master 
and cylinder indexes associated with 
the data set. It exists for any 
indexed data set that has a prime area 
occupying more than one cylinder. 



Indexed data sets must reside on mass 
storage volumes. Because an Indexed data 
set can be associated with more than one 
type of unit, it is not usually cataloged. 



DSNA8E: Required. In addition to giving 
the data set name, the DSNAPIE parameter 
identifies the area being defined, i.e., 
DSNAME-naae (INDEX) , DSNAHE=name (PRIME) , 
and DSNANE=name (OVERFLOW) . 

Igtes: 

• If the data set is temporary, name 
is replaced with SSname. 

• If only one DD statement is used to 
define the entire data set, 
DSNAME=name(PRIHE) or DSNAME=name 
should be used. 



OfilT: Required, 
The first sub 
storage unit, 
for the prime 
included, req 
units for the 
volumes. The 
be specified 
Another way o 
using the uni 
AFF. 



unless VOLUKE=SEF is used, 
parameter identifies a mass 
If separate statements 

and index areas are 
uest the same number of 

prime area as there are 

DEFER subparameter cannot 
on any of the statements, 
f requesting units is by 
t affinity subparameter. 



Creating an, Indexe d D ata Set 



Indexed data sets are created with from 
one to three DD statements. One of the 
statements must define the prime area. If 
additional areas are to be defined, the DD 
statements must appear in the following 
sequence: 



lotes: 

* DD statements for prime and overflow 
areas must indicate the same type of 
unit. 

• The DD statement for the index area 
can indicate a unit type different 
than the others. 



1. Index area 

2. Prime area 

3. Overflow area 



VOLUME : Optional. Can be used to request 
private volumes (PRIVATE) , to retain 
private volumes (RETAIN) , or to make 
specific volume references (SEE or REF) . 



This order must be maintained even if one 
of the statements is absent, only the 
first DD statement defining the data set 
can contain a name field. Other 
statements, if any, must have a blank name 
field. 

The subset of DD statement parameters 
used to create an indexed data set excludes 
the asterisk, DATA, DUMMY, DDNAME, SYSOUT, 
SUBALLOC, and SPLIT parameters. The 
remaining DD statement parameters — 
DSNAME, UNIT, VOLUME, LABEL, DCB, DISP, 
SPACE, SEP, and AFF — are all valid. 
However, certain restrictions must be 
followed in using these parameters. 



LABE L: Optional. Can be used to specify a 
retention period (EXPDT or RETPD) and/or 
password protection (PASSWORD) . 



DCB : Required. Can be used to complete 
the data control block if it has not 
been completed by the processing 
program. Either DSORG=IS or DSORG=ISU 
must be included in the list of 
attributes, even though this attribute 
was provided in the processing program. 
If more than one DD statement is used to 
define the data set, the DCB parameters 
in the statements must not contain 
conflicting attributes. 
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filSP: Optional. Must be coded to keep the 
data set (KEEP) , to catalog it (CATALG) , 
or to pass it to a later job step 
(PASS) . An indexed data set can be 
cataloged using CATLG only if all three 
areas are defined by the same DD 
statement. 

Note: 

• Indexed data sets defined by more 
than one DD statement can be 
cataloged by using the system 
utility program IEHPROGM, provided 
all volumes reside on the same type 
of unit. The utility program 
IEHPROGM is described in the 
publication OS/YS Otilities. 

SPACE; Reguired. Space must be reguested 
using either the recommended nonspecific 
allocation technigue or the more 
restricted absolute track (ABSTE) 
technique. All DD statements used to 
define the data set must request space 
using the same technigue. 

If the nonspec ific space allocatio n 
technigue is used, space must be 
reguested in units of cylinders (CYL) . 
The quantity of space requested is 
assigned to the area identified in the 
DSNAME parameter. If more than one unit 
is requested, this quantity of space is 
allocated to each volume used by the 
data set. Incremental space cannot be 
requested for indexed data sets. If one 
DD statement is used to define both the 
index and prime areas, the si^e of the 
index must be indicated in the SPACE 
parameter of the DD statement defining 
the prime area. The subparameters ELSE, 
MXIG, ALX, and ROUND cannot be used. 
Contiguous space can be requested on 
each of the volumes occupied by the data 
set with the subpararaeter CONTIG. If 
CONTIG is coded on one of the 



statements, it must be coded on all of 
them. 

If the absol ute track technigue of 
allocating space is used, the number of 
tracks must be equivalent to an integral 
number of cylinders. The address of the 
beginning track must correspond with the 
first track of a cylinder other than the 
first cylinder on a volume. If more 
than one unit is requested, space is 
allocated beginning at the specified 
address and continuing through the 
volume and onto the next volume until 
the request has been satisfied. If one 
DD statement is used to define both the 
index and prime areas, indicate the size 
of the index (in tracks) in the SPACE 
parameter of the DD statement defining 
the prime area. This number must also 
be equivalent to an integral number of 
cylinders. 

Not es: 

• The first volume to be allocated for 
the prime area of an indexed data 
set cannot be the volume from which 
the system is loaded (the IPL 
volume) . 

• space can be reguested on more than 
one volume only on the DD statement 
that defines the prime area. 

SEP AND AF F: Optional. Channel separation 
from earlier data sets can be requested 
on any of the DD statements in the 
group. In order to have areas of an 
indexed data set written using separate 
channels, units should be requested by 
their actual address (e.g., UNIT=190). 

Figure 182 illustrates a valid set of DD 
statements for creating an indexed data 
set. Note that each area is defined by a 
separate DD statement. 



| //OUTPUT 4 

I// 

\ 

I// 

I// 

I// 

J 

I// 

I// 

i 



DD DSNAME=MHB (INDEX) , UNIT=2305, DCB=DSOBG=IS , 
SPACE= (CYL, 10,, CONTIG) ,DISP= (,KEEP) 

DD DSNAME=MHB (PRIME) , DCB=DSOSG=IS, UNIT= (2305, 2) , 
VOLUME=SER=(334,335) ,DISP= (, KEEP) , 
SPACE= (CYL, 25,, CONTIG) 

DD DSNAME=MHB{OVFLOH) ,DCB=DSOEG=IS, UNIT=2305, 

VOLU ME=S ER=336 , SPACE= (CYL, 25 , , CONTIG ) , DI SP= ( , KEEP) 



Figure 182. Creating an Indexed Data Set 
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i - — ■ r 1 : 1 

I CRITERIA J Restrictions on J ( 


| Number of J Types of (Index Sizef Number of Units j Arrangement J 
j DD Statements } DD Statements J Coded? J Requested | of Areas | 
it ii i * 


i j ill l 

1 3 | INDEX | (PRIME and OYFLOH J Separate index. | 

| | PRIME | - J must specify the same J prime, and overflow ( 

) j OVFLOW j j j unit type. (areas. J 
i i i i i i 


i i i ... i . , | , , j 
I 2 | INDEX ) ] None (Separate prime and ] 
I I PHI HE | - i (overflow areas, with ( 
j 11} Jan index at the end ( 
I i ( ( (of the prime area. J 
i i i i i , , . • 


• J I I 1 .-".... f 

( 2 ( PRIME J No (Both statements must (Prime area and over- | 
| J OVFLOW ( (specify the same type (flow area with an | 
} J I (of unit. (index at its end. ( 

L t It 1 1 


r 1 1 1 J \ 

( 2 ( PRIME ( Yes (Both statements must (Prime area with em- ( 
( f OVFLOH J (specify the same unit (bedded index and ( 
I ( | (type. The statement (overflow area. J 
( | ( (defining the prime ( I 
J ( } (area cannot request J J 
( ( | (more than one unit. ( ( 
i iii i t 


r J 1 1 1 I 

( 2 J PRIME ( No (None (Prime area with index} 
( ] J ( (at its end. Unused j 
( ( ) ] ( index areas, if any, ( 
j ( j ( (used for overflow. J 
l t i i i f 


1 1 11 I ! 

( 1 ( PRIME ] Yes (Cannot request (Prime area with J 
( | J (more than one unit. (embedded index area. J 



Figure 183. Area Arrangement for Indexed Data Sets 



The manner in which the areas of an 
indexed data set are arranged is based 
primarily on two criteria: 



* The number of DD statements used to 
define the data set. 

* The types of DD statements used (as 
reflected in the DSNAME parameter) . 



An additional criterion arises when a DD 
statement is not included for the index 
area: 

• The index size and whether or not it 
has been coded in the SPACE parameter 
of the DD statement defining the prime 
area. 



Figure 18 3 illustrates the arrangements 
resulting from various permutations of the 
foregoing criteria. In addition, it points 
out restrictions on the number and type of 
units that can be requested for each 
permutation. 



8etriey.in.g_an Indexed , Data Set 

Indexed data sets are retrieved with the 
DD statement parameters DSNAME, UNIT, 
VOLUME, DCB, and DISP. Channel separation 
requests can be made using the SEP and AFF 
parameters. If all areas of the data set 
reside on the same type of unit, the entire 
data set can be retrieved with one DD 
statement. If the index resides on a 
different type of unit, two DD statements 
must be used. 

DSNAME: Required. Identify the data set 
by its name. If it was passed from a 
previous step, identify it by a backward 
reference or its temporary name. Do not 
include the terms INDEX, PRIME, or 
OVFLOS. 

_,_j__: Required, unless the data set was 
passed on one volume. Identify the unit 
type. If the data set resides on more 
than one volume and all units are the 
same type, request the total number of 
units required by all areas. If the 
index area resides on a different type 
of unit, use two DD statements, each 
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indicating the number of units of the 
specified type required. 

VOLUME ; Required, unless the data set was 
passed on one volume. Identify the 
volumes by their serial numbers (SEE) , 
listed in the same sequence as they were 
when the data set was created. 



was not completed in the program. 
Include either DSORG=IS or DSORG^ISU. 



DISjP: Required. Identify the data set as 
OLD or MOD and give its new disposition, 
to change its disposition. 



DCB: Reguired, unless the data set was 
passed. This parameter is used to 
complete the data control block if it 



Figure 184 shows how to retrieve the 
indexed data set created by the 
illustration in Figure 182. 



r 

I 

| //INPUT 

I// 
I// 
i 



DD DSNAHE=MHB,DCB=DSORG=IS,UNIT=2305,DISP=OLD 
DD DSHAME=MHB,DCB=DSORG=IS,UllIT=(2305,3) ,DISP=QLD, 
VOLUME=SER=(334,335,336) 



Figure 184. Retrieving an Indexed Data Set 
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A.£PIMIi_Ij CHECKLIST FOR JOB CONTROL P80CEDUBES 



This checklist illustrates general job 
control procedures for compiler, linkage 
editor, and execution processing. More 
than one example may be used for a job 
step, The checklist is intended as an aid 
to preparing procedures, not as an 
inclusive list of the options and 
parameters. 



If the DD * convention is used, the 
source module must follow. If another job 
step follows the compilation, the EXEC 
statement for that step follows the /* 
statement, or the last source statement. 



COMPILATION 



Case 3; Ob ject Mod ul e Is to Be Punc hed 



Figure 185 shows a general job control 
procedure for a compilation job step. The 
following cases demonstrate how to add to 
or modify the general procedure to obtain 
various processing options. 



Case 1: Compilation Only — No O bject 
Module Is to Be Produced 



Add the statement: 



//SYSPUNCH DD SYSOUT=B 



J^ote: If DECK is not the installation 
default condition, it must be specified in 
the PABM parameter of the EXEC statement. 



The general procedure should be used, 
listing is produced. It will include the 
default or specified options of the PARM 
parameter that affect output. Any 
diagnostic messages are listed, unless 
listing of warning messages is suppressed 
by the PLAGE option of the PABM parameter 
and only warning messages are produced. 



Cage_2i Source M odule from Input Stream 



Modify the end of the procedure as 
follows: 



//SYSIN DD * 

(source module) 
/* 



£ase_4i Object Module Is to Be Passed to 

Linkage .E.di tor 



Add the statement: 

//SYSLIN DD DSNAME= (subparms) , X 

// UNIT=SYSDA, X 

// SPACE= (subparms) , X 

// DISP=(MOD,PASS) 

Note: If LOAD is not the installation 
default condition, it must be specified in 
the PAfiM parameter of the EXEC statement. 



\ 

|// job name 

j//stepname 

J//SYSUT1 

I//SYSUT2 

J//SYSUT3 

J//SYSUT4 

1//SYSPRINT 

i //SYSIN 

I// 

I 



JOB acctno,name,MSGLEVEL=1 
EXEC PGM=IKFCBLOO,PAEM= (options) 
DD aNIT=SY SD A, SPACE= (subparms) 
DD UNIT=SYSDA,SPACE= (subparms) 
DD UNIT=SYSDA,SPACE= (subparms) 
DD UNIT=SYSD A, SPACE= (subparms) 
DD SYSO0T=A 

DD DSNAME=dsname,UNIT=SYSSQ,VOL0ME= (subparms) , 
DISP= (OLD, KEEP) 



Figure 185. General Job Control Procedure for Compilation 
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Case 5; Objec t Module Is to Be Saved 



The object module can be saved by 
cataloging it, by keeping it, or by adding 
it as a member of a library. Add the 
SYSLIN statement as shown in examples A, B, 
or C. 



• A. Cataloging 

//SYSLIN DD DSNAME=dsname, 

NEW 
// DISP=( ,CATLG) , 

MOD 
// VOLUME= (subparms) , 

// LABEL= (subparms) , 

SYSDA 
// UNIT= , 

SYSSQ 



// 



SPACE 

SPLIT = (subparms) 

SOBALLOC 



C. Both BASIS and COPY 

//SYSLIB DD DSNAME=basislibnarae,DISP=SHR 

// DD DSNAME=copylibname,DISP=SHR 

(DD statements for additional copylibs may 
follow.) 



• B. Keeping 



LINKAGE EDITOR 



Figure 186 shows a general job control 
procedure for a linkage editor job step. 
The following cases show how to add to or 
modify the procedure to obtain various 
processing options. 



£a,se_lj_ Input from .Previous Compilation in 

Same Job 



//SYSLIN DD DSNAME=dsname, 

NEW 
// DISP=( ,KEEP), 

MOD 
// VOLUME= (subparms) , 

// LABEL= (subparms) , 

SYSDA 
// ONIT= , 

SYSSQ 



Change the SYSLIN statement to 

//SYSLIN DD DSNAME=*.stepname.,SYSLIN, : 
// DISP= (OLD, DELETE) 

where stepname is the name of the previous 
compilation job step and ddname is SYSLIN. 
If the input is to be saved, specify KEEP 
rather than DELETE. 



// 



SPACE 

SPLIT = (subparms) 

SOBALLOC 



• C. Adding a Member to an Existing 
Cataloged Library 

//SYSLIN DD DSNAME=dsnarae(»emfcer) , 
// DISP=OLD 



Case $; COP Y St atement in COBOL Source 
Mo dule or a BASIS Card in the I nput Streai 



Add the SYSLIB (or equivalent) DD 
card (s) , as shown in examples A, B, or C. 

A. COPY 

//SYSLIB DD DSNAME=copylibnarae,DISP=SHS 

B. BASIS Card 

//SYSLIB DD DSNAME=basislibname,DISP=SH8 



Case 2; Input from System Input Stream 



Change SYSLIN statement and the end of 
the procedure as follows: 

//SYSLIN DD * 

(object module (s) ) 
/* 

If another job step follows the 
link-edit step, the EXEC statement for that 
job step follows the /* statement or the 
end of the object module. 



Cas e 3 : I nput„ „Sot _ from .Compilation .in .Same 

Job 



Specify in the SYSLIN DD statement where 
the object modules to be used as input are 
stored. (Only one member of a library can 
be specified in the SYSLIN DD statement.) 
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J//jobname JOB acctno # name, MSGLEVEL= 1 
1 



! 

1 

|//stepname 

I//SYSPHINT 

I//SYSLHOD 

I// 

J //SYS LIB 

1//SYSUT1 

J //SYS LIN 

| : 



EXEC PGM=IEWL,PARM= (options) 

DD SYSOUT=A 

DD DSNAME=&&name (member) ,UHIT=SYSDA,DISP= (NEW, PASS) , 

SPACE=(subparms) 

DD DSNAME=SYS1.COBLIB,DISP=OLD 

DD UNIT=SYSDA,SPACE=(subparms) 

DD DSNAME=dsname,DISP=OLD 



Figure 186. General Job Control Procedure for a Linkage Editor Job step 



Case_4: Output ,, to Be, Placed, in Link 



Change the SYSLMOD statement as follows: 

//SYSLMOD DD DSNAME=SYSl.LINKLIB(member) ,X 
// DISP=OLD 

where member is the name of the load module 
that is to be added to the link library- 
No other information is needed in the 
statement. 



The following cases show how to add to or 
modify the general procedure to obtain 
various processing options. 



Case 1 ; Lfi^^^odulS_io_fiS_E2e£itted_Is_in 

Link Library 



Use the general procedure, where 
progname in the EXEC statement is the 
member name of the load module. 



Ca s e_J> :. Qu t pat to. Be. Pi aced_ in private 

Lib rary 



Change the SYSLMOD statement as follows: 

//SYSLMOD DD DSNAME=dsname (member) , X 
// DISP=OLD 

where member is the name of the load module 
to be added, and dsname is the name of an 
existing library. If the library is not 
cataloged, UNIT and VOLUME parameters must 
be specified. 

Note : See "Using the DD Statement" in 
the Chapter "User Non-VSAM File 
Processing" for an example of creating 
a new library and storing the load 
module as its first member. 



Case £; Load Jjodule.tQ B e Executed Is a 

Member of Private Library 



If a STEPLIB DD statement is not in the 
JCL for the step where the program is 
reguired, then the JOBLIB DD statement must 
follow the JOB statement, as in the 
following statements: 



//J0B1 


JOB 




//JOBLIB 


DD 


DSNAME=MYLIB, 


// 




DISP= (OLD, PASS) 


//STEP1 


EXEC 


PGM=PAYROLL 



Case_6j. Output to Be Used Only, in, this Job 



The general procedure should be used. 
The load module is stored in a temporary 
library. 



EXECUTION TIME 



Figure 187 shows a general job control 
procedure for an execution-time job step. 



//STEP 2 



EXEC PGM= ACCOUNT 



The JOBLIB statement defines the private 
library MYLIB. No volume or unit 
parameters are given since the library is 
cataloged. Since JOBLIB has the 
disposition PASS, both steps can execute 
members of the library named in the JOBLIB 
statement. 
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I //stepname EXEC PGM=progname 

|//ddname DD (parameters for user-specified data sets) 



I 



Figure 187. General Job Control Procedure for an Execution-Time Job Step 



Case 3; Load Module to Be Exe cuted _ Is 
Crea ted in Previous Linkage Editor Step in 
Same Job 



Case 7; ACCEPT Is In cluded in Sourc e 
Module (Except f or F ormat 2 or ACCEP T 
MESSAGE) 



Change the EXEC statement as follows: 



//stepname EXEC PGM=*. stepname. SYSLHOD 



where stepname following PGM is the name of 
the linkage editor job step that created 
the load module. 



If the data is in the input, stream, add 
the statement: 

//SYSIN DD * 

(data) 

/* 

(See Case 2 under "General Job Control 
Procedures for a Compilation Job Step" for 
a description of the DD * convention.) 



Ca se 4: Abnormal Ter min ation Dump 



Add the statement: 



Case 8: Debug Statements EXHIBIT or TRACE 
Are Included -in^Source Module 



//SYSABEND DD SYSOUT=A 

or 
//SYSUDUMP DD SYSOUT=A 



This statement requests a full dump if 
abnormal termination occurs during 
execution. 



Ose the statement (unless it is already 
included) : 

//SYSOUT DD SYSOUT=A 

Note: If the job step already includes a 
SYSOUT DD statement for some other use, 
another need not be inserted. 



Qase_5j; DISPLAY Is Includ ed in Source 

Module 



Add the statement: 
//SYSOUT DD SYSOUT=A 



C ase 6: DISPLAY UPON SYSPUNCH Is Included 

i n Source Module 



Add the statement: 
//SYSPUNCH DD S¥SOUT=B 



Case_2i Object Time^S ymb olic Debugging 

Opti ons 



Add the statements: 

//SYSDBOUT DD SYSO0T=A required for all 

options 

//SYSDBG DD * required for SYHDHP 

option 
(control cards) 

/* 

debug DDname card also needed 



Case 10: COUNT Option 



Add the statements: 
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//3YSCO0NT DD SYSOUT=A 

//SYSDBODT DD SYSOOT=A required for all 

options 
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APPENDIX J: FIELDS OF THE GLOBAL TABLE 



In this appendix, each field of the Task 
Global Table (Figure 188) and of the 
Program Global Table (Figure 189) is listed 
by its relative location in main storage. 
Each field is further described in the 
discussion associated with Figures 188 and 
189. 



TASK GLOBAL TABLE 



The Task Global Table (TGT) is used to 
record and save information needed during 
execution of the object program. It begins 
with a series of fixed-length fields 
followed by a series of variable-length 
fields. These fields are illustrated in 
Figure 188 and are described in this 
section. 
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Relative 
Location 



72 

76 

80 
84 
88 
92 

9a 

96 

400 
404 
408 
412 
416 
420 
422 
423 
424 
428 
432 
•436 
440 
444 
452 
453 
454 
456 
460 
472 
476 
480 



Field 



(SAVE AREA 
I 



| SWITCH 
j 



|TALLY 



JSORT SAVE 

J- 



|ENTRY SAVE 



| SORT CORE SIZE 
I 



| RET CODE 



JSORT RET 



| WORKING CELLS 



JSORT FILE SIZE 
h 



JSORT MODE SIZE 



I 

JPGT-VN TABLE 
| 



ITGT-VM TABLE 



1 

|VCON PTR 



| LENGTH OF VN TBL 

I 

J LABEL RET 



1 

ICURRENT PRIORITY 



I 

JDBG R14SAVE 



1 

ICOBOL INDICATOR 



JA(INIT1) 
| 



J DEBUG TABLE PTR 



I 

JSUBCOM PTR 



| 

JSORT-MESSAGE 



JSYSOOT DDNAME 
| 



J Reserved 
1 



ICOBOL ID 



h~ 

J A (WHEN-COH PILED) INFO 



I 

J COUNT TABLE ADDRESS 



JDBG R11SAVE 



I 

| COUNT CHAIN ADDRESS 



I 

JPRB1 CELL PTR 



Figure 188. Fields of the Task Global Table (Part 1 of 3) 
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Relative 
Location 

484 

489 

492 

500 

504 

508 

512 

beginning 
of 

variable- 
length 
portion 



Field 



Unused 



TA LENGTH 



Unused 



PCS LIT PTB 



DEBUGGING 



CD FOB INITIAL INPUT 



OVERFLOW 



BL 



DECBADR 



FIB 



DEBUG TRANSFER 



DEBUG CARD 



DEBUG BLL 



DEBUG VLC 



DEBUG MAX 



DEBUG PTR 



TEMP STORAGE 



TEMP STORAGE-2 



TEMP STORAGE-3 



TEMP STORAGE-4 



BLL 



VLC 



SBL 



IND 



SUBADR 



ONCTL 



PFHCTL 



PFMSAV 



VN 



I 

(SAVE AREA-2 



Figure 188. Fields of the Task Global Table (Part 2 of 3) 
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Relative 
Location 



Field 



JSAVE AREA-3 



I 

JXSASW 



J 

|XSA 



JPARAM 
I- 



JSPTSAV AREA 



JCHECKPT CTR 
I 



JVCON TBL 
I 



(DEBUG TABLE 



Figure 188. Fields of the Task Global Table (Part 3 of 3) 
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The lengths of the variable- length 
fields are determined by the requirements 
of the prograa (if not reguired, a 
particular field may not exist in the 
object program). 

SAVE AREA 

the program* s save area; used to 
provide standard subroutine linkage 
when this program is called (by the 
Operating System or by another 
program) and when this program calls 
other programs. 



SWITCH 

a fullword switch, 
bits are used: 



Only the following 



Bit Meaning 
Indicates a size error in 
series addition or 
subtraction. If a SIZE 
ERROR clause was included in 
the source statement, and a 
size error occurs before all 
data items in the series 
have been added or 
subtracted, this bit is set 
to 1. It is tested after 
the entire addition or 
subtraction is complete. If 
the value is 1, the 
instructions generated for 
the OH SIZE ERROR clause are 
executed. 



Used for TRACE. It is set to 
1 by the execution of a 
READY statement, and reset 
to by a RESET statement. 
If the program uses a TRACE 
statement, there are 
instructions to test this 
bit at the point of 
definition for every source 
program procedure-name (PN) . 
If it is on, the DISPLAY 
subroutine (ILBODSPO) is 
called to print the card 
number of the procedure- 
name. (See "Appendix B: 
COBOL Library Subroutines" 
for a description of the 
DISPLAY subroutine.) 



Indicates program initiali- 
zation. Set to 1 by routine 
INIT3 to show that 
initialization has been 
performed. Tested by INIT3 
so that if the module is 
re-entered, INIT3 can per- 
form re-entry functions 
instead of initialization 
functions. 



10 



12 



13 

1* 
15 



Main or subprogram switch. 
Set by INIT2 if this is a 
main program. 

Used for SYMDMP. It is set 
to 1 if the symbolic debug 
option is in effect for the 
program. This bit is tested 
by the object-time COBOL 
library debugging control 
subroutine ILBQDBGO. 

Used for FLOW. It is set to 1 
if the flow trace option is 
in effect for the program. 
This bit is tested by the 
object-time COBOL library 
debugging control subroutine 
ILBODBG0. 

Dsed for STATE at program 

initialization time. If on, 
bit 10 is set on and this 
bit turned off. Thereafter 
in the object program, this 
bit is used to indicate that 
an ON OVERFLOW or ON SIZE 
ERROR condition has occurred 
for a statement. 

Used for OPT. It is set to 1 
if optimization has been 
requested for the program or 
if the SYMDMP or STATE and 
OPT, or FLOW and OPT options 
have been specified. 

Dsed for CALL, CANCEL, or a 
recursive CALL. It is set 
to 1 by the generated code 
for the CALL or CANCEL verb. 
It is tested by INIT2 to 
determine whether a 
recursive CALL condition 
exists. 

Set on in program 

initialization if STATE is 
requested. 

Used for QUOTE IS APOST. It 
is set to 1 if the 
apostrophe is to be used to 
delineate literals and to be 
used in the generation of 
figurative constants. 

Used for SYMDMP. It is set to 
1 if SYMDMP is requested and 
the program contains a 
floating-point item. 

Always set to 1. 

Indicates maximum length for a 
variable-length field. 
Before the execution of a 
Q-Routine, this bit is set 



Appendix J: Fields of the Global Table 523 



to 1 if t 
the field 
their max 
values, r 
depending 
value of 
maximum v 
of X in t 
TIMES DEP 



he VLC and SBL for 
are to be set to 
imum possible 
ather than a value 

on the current 
a data item. The 
alue is the value 
he clause "OCCURS 
ENDING 0N...«». 



X 



16 SRVBIT set on if ILBOLOM is 

link-edited with program. 
Set to 1 if COUNT is 
specified 



24-31 DECIMAL-POINT IS COMMA clause 
byte. If this clause was 
specified, the byte contains 
a comma in EBCDIC. If not, 
it contains a decimal point. 



TALLY 



a fullword used for source program 
references to the special register 
TALLY. 

SORT SAVE 

a fullword used during the execution 
of a SORT/MERGE RETURN statement to 
contain the GN for the next seguential 
instruction following the RETURN. 

ENTRY SAVE 

a fullword used to save the entry 
point of the program during INIT2 and 
INIT3 execution. 

SORT CORE SIZE 

a fullword for the SOHT-CORE-SIZE 
special register as used in the source 
program. 

RET CODE 

a ha If word for the RETURN-CODE special 
register, which is used in the source 
program to provide a completion code 
on a STOP RUN, EXIT PROGRAM, or GOBACK 
statement, or to store the return code 
from a called program. It is the 
user's responsibility to set this 
code. 

SORT RET 

a half word used to contain the return 
code from a SORT/MERGE operation. 

HORKING CELLS 

variable-length cells used by COBOL 
library subroutines called by the 
program. The total length of the 
field is 304 bytes. 

SORT FILE SIZE 

a fullword for the SORT-FILE-SIZE 
special register as used in the source 
program. 



SORT MODE SIZE 

a fullword for the SORT-MODE- SIZE 
special register as used in the source 
program. 



PGT-VN TBL 

a fullword pointer to that part of the 
VN field of the PGT containing VN»s 
for independent segments. 



TGT-VN TBL 

a fullword pointer to that part of the 
VN field of the TGT containing VN's 
for independent segments. 

VCON PTR 

pointer to the VCON TBL field of the 
TGT. This is reguired because the 
VCON TBL field is variably located, 
and the VCON PTR is fixed within the 
TGT. 

LENGTH OF IND VN TBL 

a half word containing the length of 
that part of the VN field (the length 
is the same for both the TGT and PGT) 
containing VN's for the independent 
segments. 

LABEL RET 

the LABEL-RETURN special register for 
nonstandard labels, If an error 
occurs in such a label, it is the 
user's responsibility to place a 
nonzero value into this 1-byte cell. 



CURRENT PRIORITY 

for a segmented progr 
segmentation subrouti 
inserts the priority 
currently in the tran 
field is initialized 
current priority cell 
segmented programs to 
priority of the segme 
loaded, subroutine I 
to determine whether 
initialize the segmen 
in a branch. 



am, the 

ne ILBOSGM0 

of the segment 

sient area. This 

to 0. The 

is used in all 

store the 
nt currently 
LBOSGM0 uses it 
to load and/or 
t of destination 



DBG R14SAVE 

indicates the contents of register 14. 
A routine of the debug control 
subroutine ILBODBG0 is called to save 
this information before the execution 
of any instruction that passes control 
outside the COBOL program. 

COBOL INDICATOR 

identifies the object program as an 
OS/VS COBOL program. 

INIT1 ADCON 

address of INIT1 used for GOBACK, STOP 
RUN, and EXIT PROGRAM instructions, 
and for segmentation coding. 
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TGTTAB PTR 

if the FLOW SYMDMP or STATE compiler 
options are specified, this field 
points to the TGTTAB. 



DEBUGGING 

a fullword cell containing the address 
of the beginning of the debugging 
cells in the variable portion of this 
table. 



SOBCOM PTR 

a pointer to the subroutine 
communications (SUBCOM) area in the 
COBOL subroutine library. 

SORT -MESS AGE 

an 8-byte area for the SORT-MESSAGE 
special register, which is used in the 
source program to allow the user to 
specify to the Sort/Merge program 
where to place the messages it issues. 

SISOUT DDNAME 

a 1-byte area with the STSx character. 

COBOL ID 

contains the identifying number of the 
compiler. 

WHEN-COMPILED ADDRESS 

Address of WHEN-COHPILED information 
in INIT1. 

COUNT TABLE ADDRESS 

Relative address of the COUNT table 
from the beginning of the TGT. The 
COUNT table is located between the 
Q-routines, if any, and the INIT2 
routine. The count table is used only 
when the program terminates. 

DBG R11SAVE 

indicates the contents of register 11. 
When the dynamic dumping routine of 
the debug control subroutine ILBODBGO 
receives control, it places the return 
address to the in-line code of the 
calling program in register 11. 
Therefore, the contents of register 11 
must be saved. 

COUNT CHAIN ADDRESS 

Address of the COUNT CHAIN for this 
program. The address is initialized 
to zero if count is specified; the 
address is filled in at execution 
time. 

PRBL1 CELL PTR 

a fullword cell containing the address 
of the first PROCEDURE BLOCK cell in 
the PGT. 

TA LENGTH 

a half word initialized to the length 
of the largest segment with a nonzero 
priority. 

PCS LIT PTR 

a fullword cell containing the address 
of the PCS (Program Collating 
Sequence) alphabet. 



CD FOR INITIAL INPUT 

a fullword cell containing the address 
of the CD area with INITIAL INPUT 
clause. 

OVERFLOW 

if the TGT is longer than 4096 bytes, 
this field contains one fullword cell 
pointing to each 4096-byte area after 
the first. The cell is loaded into a 
register when a base is required for 
the overflow area. 

BL 

base locators. Each BL cell is a 
fullword containing an address in the 
data area. There is one BL pointing 
to the beginning of the Working- 
Storage Section and one for each file 
in the File Section. More than one BL 
is assigned if an area is larger than 
4096 bytes. 

DECBADR 

DECB addresses. There is one fullword 
cell pointing to the address of the 
DECB for each basic file. 

FIB 

File Information Block addresses. 
There is one fullword cell pointing to 
the address of the FIB for each VSAM 
file. 

DEBUG TRANSFER 

a 1-byte cell that indicates the type 
of invocation for a PN. 

DEBUG CARD 

a 2-byte cell containing the card 
number. 

DEBUG BLL 

a 2-byte cell containing the 
displacement to the BLL cell, 

DEBUG VLC 

a 2-byte cell containing the 
displacement to the VLC cell. 

DEBUG MAX 

a 2-byte cell containing the maximum 
size of DEBUG-ITEM. 

DEBUG PTR 

a fullword cell containing a pointer 
used by ILBOBUG to reference the debug 
subscript table. 

TEMP STORAGE 

temporary storage for arithmetic 
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operations. TS space is allocated in 
doubleword blocks. 

TEMP STORAGE-2 

temporary storage for nonarithmetic 
instructions. These cells are 
variable in length. 

TEMP STORAGE-3 

temporary storage used to align fields 
of data described by the SYNCHRONIZED 
option. The field begins on a 
doubleword boundary. 

TEMP STOBAGE-4 

temporary storage cells used for the 
SEARCH AIL table-handling verb. The 
field starts on a doubleword boundary. 



BLL 



VI C 



SBL 



base locators for the Linkage Section. 
Each BLL cell is a full word containing 
the address of an area passed as a 
result of an ENTRY statement, a label 
record, a totaled area, a sort 
description entry, or a GIVING option 
in a OSE... ERROR statement. 



variable-length cells. Each VLC is a 
halfword whose value is set by the 
execution of a Q- Routine. It contains 
the current length of a variable- 
length field. There is one VLC for 

each OCCGES DEPENDING ON clause and 

all items to which it is subordinate. 



secondary base locators. Each SBL 
cell is a fullword set by the 
execution of a Q-Routine. It contains 
the current address of a field which 
is variably located because it follows 
a variable-length field. 



IND 



fullword cells, each containing the 
current value of an INDEX-NAME. There 
is one IND cell for each implicitly- 
defined INDEX-NAME. (Explicitly- 
defined INDEX-NAMEs are not listed 
in these cells.) 

SUBAD1 J 

subscript addresses. Each SUBADR cell 
is a fullword containing the address 
for a subscripted reference. 

ONCTL 

control counters for ON statements. 
Each is a fullword initialized to 0. 

PFMCTL 

PERFORM control counters and DEBUG 
saved location. Each PFMCTL cell is a 
fullword used for a PERFORM n TIMES 
statement to count the number of times 
the procedure has been performed. For 



DEBUG, a PFMCTL cell is used to save 
the contents of reqister 14 when the 
DEBUG packet is entered. DEBUG 
packets are called by BALE 14,15. 

PFMSAV 

PERFORM saved locations. Each is a 
fullword used to contain an address. 
For PERFORM, the cell is used to store 
the address of the next sequential 
instruction after the performed 
procedure, when that procedure is 
being executed because of a PERFORM. 
This is to enable the procedure to be 
executed in-line. 

VN 

variable procedure-names. Each VN 
cell is a doubleword containing the 
current address of a branch point 
which may change during program 
execution because of an ALTER or 
PERFORM statement. 

SAVE AREA-2 

pointer to the save area for label- 
and error-processing declaratives. 

SAVE A RE A- 3 

variable number of fullwords used for 
OPEN parameters. 



XSASW 



XSA 



1-byte EXHIBIT switches. These are 
used as first-time switches for the 
coding generated for the EXHIBIT 
CHANGED statement. They are also used 
in certain types of SORT statements 
and ON statements. 



EXHIBIT saved area cells. These are 
variable in length and are referred to 
in the coding generated for an EXHIBIT 
CHANGED statement. There is one XSA 
for each operand to be exhibited with 
a CHANGED option. These cells are 
also used for SORT and RELEASE verbs. 

PARAM 

parameter area of fullwords, 
containing parameter lists for macro 
instruction expansions of certain 
source statements. The size of the 
parameter area equals the largest 
number of words required for any one 
expansion. 

RPTSAV 

six words used to save branch 
addresses during the execution of 
Report Writer routines, if the Report 
Writer is used. 

CHECKPT CTR 

fullword cells used to count the 
number of file records processed for a 
file for which checkpoints are to be 
taken. 
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VCON TBL 

8-byte V-type address constants for 
nonresident segments. The format of 
each entry is: 



lite 


1-3 
4-7 



Contents 
Priority number 




VCON to independent segaent 



DEBUG TABLE 

table used by the flow trace and 
statement number and symbolic debug 
COBOL library subroutines. The format 
depends on the options specified. 



• If the FLOW compiler option is 
specified: 



Byte (s> Content s 

Number of traces requested 

1-3 Unused 



• If the STATE option is specified: 



Byte is) Contents 

0-3 Start of Q-Routines, or if 

none, start of INIT2. 
4-7 Size of Declaratives (not 

including Report Writer) 

Section. 
8-11 Starting address of P80CTAB 

in object module. 
12-15 Starting address of SEGINDX 

in object module. 
16-19 Ending address of SEGINDX 

in object module. 



• If both the FLOW and STATE compiler 
options are specified: 

Byte (s) C onte nts 

Number of traces requested 
1-19 The same as shown above for 
the STATE option. 



• If the SYMDMP option is specified: 

B yte (s) Cont ents 

0-3 Start of Q- Routines, or if 

none, start of INIT2. 
4-5 Hashed compilation indicator. 

• If both the SYMDMP and FLOS options 
are specified: 

Byte (s) Conte nts 

Number of traces requested. 
1-5 The same as shown above for 
the SYMDMP option. 



DEBUG LINKAGE AREA 



SYMDMP LINKAGE AREA 



COUNT LINKAGE AREA 



TEST LINKAGE AREA 



OVERFLOW 



VIRTUAL 



VIRTUAL EBCDIC NAMES 



PN 



k— 



GN 



DCBADR 



VNI 



LITERAL 



DISPLAY LITERAL 



PROCEDURE BLOCK 



Figure 189. Fields of the Program Global 
Table 



PROGRAM GLOBAL TABLE 



The Program Global Table (PGT) contains 
data referenced by procedure instructions. 
All the fields in the PGT are variable in 
length. PGT data is never modified by 
procedure instructions; rather, it remains 
constant throughout program execution. 



The fields in the PGT are illustrated in 
Figure 189 and described in the text below. 



DEBUG LINKAGE AREA 

a 12-byte area that contains the 
linkage for dynamic dumps. If the 
SYMDMP option is not specified, this 
area does not exist. 



SYMDMP LINKAGE AREA 

a 12-byte area that contains the 
linkage to the SYMDMP routine for 
dynamic dump requests. 



COUNT LINKAGE AREA 

8-byte area that contains the linkage 
to the COUNT routine. If the COUNT 
option is not specified, this 8-byte 
area does not exist. 
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TEST LINKAGE AREA 

16-byte field that contains the 
linkage to the IBM OS COBOL 
Interactive Debug Program Product 
(Program No. 5734-CB4) when TEST was 
specified for compilation- 



instruction in a block of coding. The 
addresses of the PN*s are in the same 
order as their definition in the 
source program. The program branches 
by loading an address from the PGT and 
then branching to it. 



OVERFLOW 

if the entire PGT exceeds 4096 bytes 
in length, there is one fullword 
OVERFLOW cell pointing to each 
U096-byte section after the first. 
The cell is loaded into a register 
when a base is needed to refer to the 
section of the PGT. 



VIRTUAL 

each vi 
the add 
(the re 
object 
or the 
If eith 
effect, 
library 
EBCDIC 1 
the DYN 
virtual 
sub prog 
displac 
from th 
reguire 
in the 
COBOL 1 



rtual is a f 
ress of an e 
suit of an E 
module) unle 
RESIDENT opt 
er of these 
the virtual 
subroutines 
/ 00 00 00'; 
AM option is 
s correspond 
rams contain 
ement of the 
e beginning 
d because of 
source progr 
ibrary objec 



ullword containing 
xternal procedure 
SD and RLD in the 
ss either the DYNAM 
ion is in effect, 
options is in 
s corresponding to 

are written as 
/ in addition, if 

in effect, the 
ing to user 

the relative 

subprogram name 
of the PGT. It is 

a CALL statement 
am or a branch to a 
t-time subroutine. 



VIRTUAL EBCDIC NAMES 

indicates the EBCDI 
subroutines and use 
either the DYNAM or 
option is in effect 
of all library subr 
be dynamically load 
addition, if DYNAH 
EBCDIC names of all 
that are to be dyna 
listed. Each VIRT0 
is a double word con 
the subroutine or s 
justified and padde 
necessary. If neit 
RESIDENT is in effe 
not exist. 



C names of library 
r subprograms. If 

the RESIDENT 
, the EBCDIC names 
outines that are to 
ed are listed; in 
is in effect, the 

user subprograms 
mically called are 
AL EBCDIC NAME cell 
taining the name of 
ubprogram, left 
d with blanks if 
her DYNAM nor 
ct, this field does 



PN 



source program procedure- names. When 
the OPT option is in effect, only 
those PN's associated with ALTER and 
declaratives references receive PN 
cells. Each PN cell is a fullword 
containing the address of the first 



GN 

compiler-generated procedure-names. 
When the OPT is in effect, only those 
GN's associated with AT END and 
INVALID KEY references receive GN 
cells. Each GN is a fullword 
containing the address of the first 
instruction in a block of coding. 
GN*s are used in the same way as PN*s. 
They were generated to provide 
addresses for branches implied but not 
stated in the source program. They 
are stored in the PGT in the order in 
which they were generated. 

DCBADR 

DCB addresses. Each DCBADR cell is a 
fullword containing the address of a 
data control block in the data area of 
the program. There is one DCBADR cell 
for each DCB generated. 



VNI 



variable procedure- name initialization 
cells. There is one doubleword VN 
cell for each variable procedure-name 
in the program. It contains the 
initial value of the VN, and is used 
to initialize the VN values in the 
TGT. VN's are generated to contain 
branch addresses which vary because of 
PERFORM or ALTER statements. 



LITERAL 

literals referred to by procedure 
instructions. The literals are 
variable in length. There is no 
duplication in storage, since 
duplicate literals were eliminated. 

DISPLAY LITERAL 

literals used by calling sequences 
rather than instructions. They are 
variable in length; duplication was 
eliminated. each cell is a fullword 
containing the address of a procedure 
block. The compiler assigns these 
cells only when the OPT option is in 
effect. 

PROCEDURE BLOCK 

each cell is a fullword containing the 
address of a procedure block. The 
compiler assigns these cells only when 
the OPTIMIZE option is in effect. 
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This appendix contains the COBOL 
object-time messages (including those 
messages issued by the queue-analyzer 
subroutine) and briefly describes how to 
generate a listing of COBOL compile- time 
messages. 



COMPILE-TIHE MESSAGES 



The user can request 
of the diagnostic oessag 
compiler by compiling a 
prog ram- name of ERRMSG s 
PROGRAM-ID paragraph. F 
the formats of compiler 
information about genera 
see "Compiler Output" in 
of this publication. 



a complete listing 
es issued by this 
program with a 
pecified in the 
or a description of 
diagnostics and 
ting this listing, 
the "Output" part 



If the compiler encounters a D-level 
("disaster") error situation, and the user 
program being processed had specified the 
DUMP compile option, then the associated 
error message for that situation is in most 
cases not produced. (The additional 
processing needed to produce the message 
would alter the contents of internal 
storage and thus reduce the dump's value.) 
In place of the message, the compiler 
issues a four-digit o-type completion code 
along with the resultant abend dump. A 
list of these codes and an indication of 
their origin within the compiler phases can 
be found in the manual IBM O S/ VS COBOL 
Co mpiler Program Logic, order No. 
LY28-6486. 



OBJECT-TIME MESSAGES 



The COBOL library subroutines issue both 
informative messages and an occasional 
0- type abend completion code. 
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The abend (initiated by ILBOSRV) may 
follow a terminal message. 

U030 3 The time stamp of the volume 
on which a VSAM data set is 
stored does not match the system 
time stamp in the data set's 
catalog record. ILBOVOC 
initiates the abend. 

U0304 The time stamps of a VSAM data 

component and an index component 
do not match, indicating that 
either the data or the index has 
been updated separately from the 
other. ILBOVOC initiates the abend. 

U0519 Execution has reached the bottom of 
the Procedure Division, but does not 
find a STOP RUN, GO BACK, or EXIT 
PROGRAM statement. An error exists 
in the program's logic flow. The 
abend is initiated by the compiler- 
generated object code. A warning 
about the situation may have been 
issued at compile time. 

U1301 I/O error for a non-QSAM/VSAM file 
for which no error declarative was 
coded. ILBOSYN initiates the abend. 

03361 The PCCNTROL name is not the same as 
the current COBOL program name and 
SYMDMP was not cancelled. ILB0D21 
initiates the abend. 

,03440 Insufficient main storage is 
available, or an invalid 
GBTMAIN/FREEMAIN request has 
occurred. The abend (initiated by 
ILBOCMM) follows message IKF993I or 
IKF994I. 



Co mp le tion Codes 



03505 A f low-of-control error has been 

discovered. The abend (initiated by 
ILBODBG1) follows message IKF193I. 



00187 An incorrect compiler-generated verb 
table has been discovered. The 
abend (initiated by ILBOTC3) follows 
message IKF187I. 

U02Q3 An attempt to divide by zero 

(normally causing an ABEND OCB) 
was detected by ILBOXDI, and ON 
SIZE ERROR was not specified. 
Register 14 points to the location 
in the program that caused the 
error . 

•00295 The Return Code (RC12) has been 

changed from positive to negative. 



informative Messages 



The following messages are preceded by a 
system-generated 2-character numeric field, 
which is used to identify the program 
issuing the message and may be required in 
the operator response. 
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IKFOGOA- xxx 

Explanation: This message is 
generated by the STOP statement 
with the 'literal' option. The 
message text is supplied by the 
object program and may indicate 
alternative action to be taken. 

System., Action: The object 
program enters wait state. 

Programmer Response: Check 
message text supplied by the 
object program on alternative 
action to be taken. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

Operator Response: Follow 
instructions given by the 
programmer when program was 
submitted for execution. If 
the job step is to be resumed, 
enter 

REPLY xx, »y« 

where j is any single 
character. Processing 
continues. 

£KF111I Text as supplied by system 
SYNADAF routine. 



IKF115I 



Explanation: 
is provided 
input/output 
other except 
condition ha 
provisions w 
it within th 
The data set 
control is r 
higher level 



This i 
when a p 

error o 
ional in 
s occur r 
ere made 
e COBOL 

is not 
eturned 

program 



nf ormation 
ermanent 
r some 
put/output 
ed and no 

to handle 
program, 
closed and 
to the next 



programmer Response: Probable 
user error. Include an 
input/output error declarative 
for the appropriate file to 
process the error condition. 

If the problem recurs, have 
the following available before 
calling IBH for programming 
support: source deck, control 
cards, and compiler output. 

Operat or Response: Probable 
user error. Supply the 
programmer with the console 
message. 



IKF120I 



IKF129I 



QSAM ERROR AT DISPLACEMENT nnnn 
IN PROGRAM xxxx — FILE 
STATUS IS yy 

Explanation: An error which 
would result in a FILE STATUS 
value of 90 or higher 
(identified by yy in the 
message) has been encountered 
at the relative displacement 
identified by nnnn in the 
COBOL program whose PROGRAM- ID 
is xxxx; however, a FILE 
STATUS clause was not specified 
and no error declarative was 
active for the QSAM file. 

System Action : COBOL terminates 
execution of the program and 
returns to its caller with a 
return code of 12. 

Programmer Response: Correct 
the indicated error. Consider 
adding a FILE STATUS clause to 
intercept such errors for 
in-prograra handling. 

TABLE OVERFLOW. TOO HANY 
DYNAHIC CALLS. 

Explanatio n: This message is 
issued when the number of 
dynamic calls exceeds that 
which the compiler can process. 



System Action : 
terminated. 



The run is 



Programmer. Response: Probable 
user error. Reduce the number 
of dynamic calls and rerun the 
job. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

UNEXPECTED DATA FOLLOWING 
LAST SLASH IN PARM FIELD, 
LAST SLASH AND UNEXPECTED 
DATA TRUNCATED. 

Explanation : A slash is 
required to separate user- 
defined parameters from 
COBOL-SBfined parameters in 
the PARM field of the EXEC 
statement at execution time. 

System Action : The last slash 
and all data following it in 
the PARM field are truncated 
and not passed to the object 
program. 
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Programmer Response ; Correct 
the data following the last 
slash to contain only those 
items expected by COBOL for 
execution time (see the 
section "Options for Execution" 
in the chapter "Job Control 
Procedures") . 

IKFUOI NO STORAGE AVAILABLE FOB STAE. 
ALL DEBUGGING OPTIONS 
CANCELLED. 

Sys tea -.Act ion: ft H debugging 
options are canceled. 

Programme r Res po nse ; Probable 
user error. Increase REGION 
SIZE and re-execute the 
program. 

If the problem recurs, have 
the following available before 
calling IBH for programming 
support: source deck, control 
cards, and compiler output. 

IKF141I- INSUFFICIENT INFORMATION PASSED 
BY STAE ON ABEND. RERUN JOB. 



IKFU3I-* INSUFFICIENT FL08 TRACE TABLE 
SPACE. 

Explanati on: The Operating 
System GETHAIN macro 
instruction returned a nonzero 
code, indicating that 
sufficient space in the region 
is not available for the Flow 
Trace table. 

Syste m Action: Flow output is 
canceled for the program. 

Programmer,, Response: Probable 
user error. Increase REGION 
SIZE and re-execute the 
program. 

If the problem recurs, have 
the following available before 
calling IBM for programming 



Sy stem Acti on: All debugging 
options are canceled. 

Programmer Re sp onse: Probable 
user error. Increase REGION 
SIZE and re-execute the 
program. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 
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support: source deck, control 
cards, and compiler output. 



IKF155I- STATEMENT NUMBER ERROB, 



If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 



Expl ana tion: A comp 
logic error has occu 
STATE option process 
certain conditions, 
may result from othe 
errors. For example 
might destroy some o 
information reguired 
STATE subroutines; a 
branch might cause a 
non-existent priorit 
be stored in the TGT 



iler or 
rred during 
ing. Under 
this error 
r user 
, a loop 
f the 

by the 
n invalid 

y-number to 
, etc. 



System Actio n: STATE option 
canceled. 

Prog ra mmer .. Response: If the 
problem recurs, have the 
following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF158I-* TOO MANY PROGRAMS TRACED. 

Explanation: The FLOW option 
is effective in a subprogram 
structure of more than 10 
programs compiled with the FLOS 
option. 

System Action: Programs 11 and 
higher are identified by 
asterisks in the PROGRAM-ID 
print field. Tracing, however, 
continues. 

Pro grammer Response: None. 

IKF159I-* NO PROCEDURES TRACED. 



Explanation: Abnormal 
termination has taken place 
before any COBOL statement with 
a procedure-name could be 
traced. 



System Actio n: 
done. 



No tracing is 



Programmer Respo nse : Probable 
user error. If a trace is 
desired, recompile the program 
after inserting additional 
procedure-names. 



♦Only the message number, and not the text 
of the message, is printed on the system 
output listing. 



IKF160I- IDENTIFIER NOT FOUND - ****. 



Explanation: The **** 
identifier specified on a 
line-control card was not 
defined in the Data Division of 
the COBOL program. 

System Action : The dump 
reguest on the line-control 
card for this identifier is 
ignored. 

Prgig£amme r Response: Probable 
user error. Rewrite the 
line-control card indicated to 
include the reguired 
identifier. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF161I- CARD NUMBER NOT FOUND. 

Expla nation: The line-num 
parameter of the line-control 
card must correspond to the 
generated card number directly 
preceding that for the data 
card at which the formatted 
dump is to begin. 

System Acti on : The 
line-control card with 
non-existent card number is 
skipped, 

Programme r Re sponse: Probable 
user error. Substitute the 
correct card number for the 
incorrect specification 
indicated. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF162I- VERB NUMBER NOT FOUND. 

Expl a nation: The verb-num 
parameter of the line-control 
card specifies a verb number 
that does not exist in the line 
specified by the corresponding 
line-num parameter. 
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IKF163I- 



Systej, Action; The 
line-control card with the 
non-existent verb number is 
skipped. 



Programm er Response: Probable 
user error. Substitute the 
verb number desired. 



If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

NO ROOM TO DUMP. 



Explanation: There is 
insufficient space for a 
symbolic dump to be generated. 

System Action: A Data Division 
dump (and sometimes COBOL 
statement number message) is 
not given. 

Progr amm er Res po nse: Probable 
user error. Include an 
additional 22K in the REGION 
parameter of the EXEC statement 
when the SYMDMP option is 
specified. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF164I- I/O ERROR ON DEBUG FILE. 

Ex planation : The SYSUT5 file 
must be specified when symbolic 
dumping is requested. 

System Action: The SYMDMP 
output is canceled for the 
program. 

Programmer Respons e: Probable 
user error. Include an 
additional DD card for the 
SYSUT5 file. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF165I- SRONG DEBUG FILE FOR PROGRAM. 

Explanation: An additional 
data set, SYSUT5, is required 
when symbolic dumping is 
requested. 



System Action: SYMDMP output 
is canceled for the program. 

Programmer Response: Probable 
user error. Include an 
additional DD card for the 
SYSUT5 file. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF166I- NO ROOM FOR DYNAMIC DUMPS. 

Explanation: There is 
insufficient space for a 
symbolic dump to be generated. 

System Action: Dynamic 
dumping, but not abnormal 
termination dumping, is 
canceled for the program. 

££22r a mmer_ Response: Probable 
user error. Include an 
additional 22K in the REGION 
parameter of the EXEC statement 
when the SYMDMP option is 
requested. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF167I- INVALID FILE-NAME. 



lOlaijation: An additional 
data set, SYSUT5, is required 
when symbolic dumping is 
requested. 

System Action: SYMDMP output 
is canceled for the program. 

Prpgrammer Response: Probable 
user error. Include an 
additional DD card for the 
SYSUT5 file. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

UNSUCCESSFUL OPEN OF DEBUG 
FILE. 

Expla n ation: A GO. SYS DBG DD 
card is required when SYMDMP is 
specified. 

Sl§tem_Action: SYMDMP output 
is canceled for the program. 



IKF168I- 
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Programmer Response: Probable 
user error. Check for a 
missing or incorrectly punched 
DD statement. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF169I- HISSING PARAMETERS. 

MBianation: A program 
requesting symbolic dumping 
must include both 
program-control cards and 
line-control cards with their 
several parameters. 

Syste m Action: The option with 
the missing parameter is 
ignored. 

Pr o grammer R espons e: Probable 
user error. Include the 
parameter (s) missing from the 
program- control/line-control 
cards. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF170I- INVALID OPTION. 



Exp l anatio n: The program 
control card can include only 
the IBM-designated options. 

System Action: Execution 
continues. 

Programmer Response: Probable 
user error. Check for 
misspelled option names on the 
program control card before 
rerunning the job. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

SUBSCRIPTING ILLEGAL 

Ex pl ana tio n: The line- control 
card contains subscripted 
naaesin the »NAME1[THRU NAME2]» 
option. Subscripting is not 
permitted. 

System Action: Subscripting is 
ignored. Every occurrence of 
the name is printed. 



IKF171I- 



Programmer, Response: Probable 
user error. Remove subscript 
from » NAME1[THRU NAME2 ]' 
option. 



If the problem recurs, have 
the following available before 
calling IBS for programming 
support: source deck, control 
cards, and compiler output. 

IKF172I- ON PARAMETER TOO BIG. 

Explanation: None of the 
parameters specified in the ON 
option of a line-control card 
can exceed 32767. 

S 2 § te m _. Ac t i on : The number is 
reduced to 32767. 

Program me r R esponse : Probable 
user error. Respecify the 
parameter indicated. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

Note: Messages IKF160I through IKF172I 
(except IKF170I) may appear interspersed 
among the SYMDMP control cards at the point 
at which the error is recognized. 
PROGRAM-ID is specified for messages 
IKF163I through IKF172I (except IKF170I) . 
For messages IKF160I through IKF162I, the 
PROGRAM-ID is that of the nearest preceding 
program-control card, and the card/verb 
number of the corresponding line-control 
card is given instead. Messages IKF163I 
through IKF165I may also appear in the 
midst of the dump output if the error 
condition is not recognized until dumping 
begins. 



IKF17 3I- SYMDMP/STATE/FLOW INTERNAL 

ERROR. EXECUTION CANCELLED. 

Explanation: This message is 
issued when an exceptional 
input/output condition has 
occurred and no provisions were 
made to handle it within the 
COBOL program. 



Sis t em _ Ac t ion : 
canceled. 



The job is 



Programmer .Response: Probable 
user error. Rereun the job. 
If the problem recurs, have the 
following available before 
calling IBM for programming 
support: source deck, control 
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cards, and execution-time 
output. 



necessary linkage code before 
rerunning. 



IKF174I- 



SYMDMP CANCELLED. 
CARDS FOUND. 



NO CONTROL 



IKF175I- 



IKF176I- 



E xplan ation: Programs run with 
the SYMDMP option must include 
both object-time control cards 
and program control cards. 

System Action: The SYMDMP 
option is canceled. 

Programmer, Response: Probable 
user error. Provide the 
necessary control cards before 
rerunning the job. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

COBOL PROG RAH WITH DEBUGGING 
NOT FOUND. 

Explanat io n: Either standard 
linkage conventions were not 
followed or the program in 
which the abnormal termination 
took place was a COBOL program 
with no debugging options or a 
non-COBOL program. 

Sjrstem_Action: No debugging 
information is generated. 

Program mer Response: Probable 
user error. Verify that 
standard linkage conventions 
are followed and then check for 
the possibility that the 
abnormal termination is in a 
COBOL program with no debugging 
options or a non-COBOL program. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and execution-time 
output. 



NO SAVE AREA CHAIN. 
CANCELLED. 



SYMDMP 



Explanation: standard linkage 
conventions must be followed in 
a calling-called seguence. 



System .Action : 
is canceled. 



SYMDMP output 



IKF177I- 



IKF180I- 



IKF181I- 



If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and execution-time 
output. 



USER ERROR FOUND. 
FOLLOWS. 



DEBUG OUTPUT 



Pro grammer Response: Probable 
user error. Provide the 



Explanation: This message is 
issued when an exceptional 
input/output condition has 
occurred and no provisions were 
made to handle it within the 
COBOL program. 

System Ac tion : Debugging 
information is generated and 
the job step is canceled. 

Programmer Response: Probable 
user error. Rerun the job. If 
the problem recurs, have the 
following available before 
calling IBM for programming 
support: source deck, control 
cards, and execution-time 
output. 

DEBUG CANCELLED. UNABLE TO 
OPEN OUTPUT DATA SET. 

Explanation: when the SYMDMP 
option is in effect, the 
SYSDBOUT DD data set must be 
reguested. 

System A ction: All debugging 
options are canceled. The 
following message is issued at 
the console: DEBUG CANCELLED. 
UNABLE TO OPEN OUTPUT DATA SET. 

Programmer Res ponse: Probable 
user error. Provide a SYSDBOUT 
DD card before rerunning the 
job. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and execution-time 
output. 

NO PCONTROL ENTRY FOUND FOR 
PROGRAM-ID NAMED. SYMDMP 
CANCELLED. 

Explanation: PROGRAM-ID has 
not been found on the PCONTROL 
card. Possibly mispelled. 
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System Actio n: SYMDMP output 
is canceled for the pro gran. 



IKF18 6I- 



COUNT OPTION CANCELED. UNABLE 
TO OPEN SYSCODNT DATA SET. 



Programmer Response: Probable 
user error. Correct the 
spelling of the PROGRAM-ID on 
the PCONTROL card. 



Explanation: When the COUNT 
option is in effect, the 
SYSCOUNT data set must be 
available. 



IKF182I- UNINITIALIZED OR INVALID BASE 
ADDRESS FOR DATA ITEM ABOVE 

Explan ation: Base locator for 

identifier has not been 

initialized (for example, an 

identifier in a record 

associated with an unopened 

FD). IKF187I- 

svstea Actio n: Value of 
identifier is not printed. 

Programmer Respons e: None. 

IKF183I- SPACE NOT FOUND FOR THE COUNT 
CHAIN. CONTINUING. 

Explanat ion: There is not 
enough space for the count 
chain. 

System A ctio n: The count 

output for the program is 

canceled for this entry into 

the program unit. IKF191I- 

Programm er Res po nse : Increase 
the size of the region and 
re-execute the program. 

IKF184I- SPACE NOT FOUND FOR THE VERBSUM 
TABLE. CONTINUING. 

Explanation: There is not 
enough space for the VERBSUM 
table. 

S yste a_ Action: Verb statistics 
are not printed. 

Progra mmer Response : I n c r ea se 
the size of the region and 
re-execute the program. 

IKF185I- COUNT OPTION CANCELED. NO 
CORE. 

Explan a tion : There is not 

enough storage for the COUNT 

option. IKF192I- 

Sys tem A ction: The COUNT 
option is canceled. 

Programmer Resp on se : Increase 
the size of the region and 
re-execute the program. 



System .Action: The COUNT 
option is canceled. 



Pr ogrammer Res ponse: Provide a 
SYSCOUNT DD card before 
rerunning the job. 

INVALID COUNT TABLE ENTRY. NO 
STATISTICS. 

Explanati on: An entry in the 
count table is invalid. 

Syg t em_ Act i on : User ABEND 187 
will occur. 

£££ gr a 3JS££_ Response : This 
message should not occur. Have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler- and 
execution-tiae output. 

MAXIMUM CARD NUMBER EXCEEDED. 
NUM OPTION CANCELLED. 

Explanation: The NUM option is 
in effect, and the maximum card 
number {999999) is given for a 
card that is not the last in 
the program. 



System _ Ac t i on : 
is canceled. 



The NUM option 



Progra mmer Re sponse: Probable 
user error. Reassign card 
numbers so that only the last 
card in the program is given 
the number 999999. 

If the problem recurs, have 
the following available before 
calling IBM for programming \ 
support: source deck, control 
cards, and execution-time 
output. 

SYMDMP OR TEST OPTION CANCELLED 
DUE TO NUM SEQUENCE ERROR. 

E xplanation : Either SYMDMP or 
TEST is in effect and the NUM 
option has been canceled 
because of other error 
conditions. 
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Pr ogr ammer Response: Probable 
user error- correct the errors 
indicated and rerun the job. 



If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and execution-time 
output. 

IKF193I- ERROR IN FLOW OP CONTROL— JOB 

CANCELLED IKF431I-E 

Explanation: In a 
multi-language environment in 
which COBOL is not the 
highest-leyel program in the 
run-unit, ILBGSTPO was not 
called prior to calling the 
first COBOL subprogram. 

System. Action: Abend U3 505 
will occur (issued by 
ILB0DBG1). 

Programmer Response: Probable 

user error. Ensure that 

ILBGSTPO is called prior to 

calling the first COBOL IKF44 0I-E 

subprogram. 

IKF400 These messages are produced 

through by the Communication job 

IKF411 scheduler (CJS) utility. Since 

this utility (written in COBOL) 

is subject to user 

modification, the text and 

meanings of these messages are 

also subject to change. 

Consult the current CJS program 

listing. 

IKF430I-E nric ENABLE TO WRITE STARTED 
MESSAGE TO CJS. RUN 
TERMINATED. 

Explanation: The job-started 
messages required by the 
Communication Job Scheduler 
(CJS) from the job it has IKF555I- 

scheduled cannot be sent. The 
value nn is the CD status key 
associated with the error. The 
value c is the CD type: I for 
input, O for output. 



System Action: 
terminated. 



The run unit is 



Programmer Response: If nnc = 
201: the queue structure 
specified in the PARM field for 
the scheduled program cannot be 
accessed; ensure that the 
COBTPQD DD card is present (if 
required) , and that a DD card 



for the queue responsible for 
the scheduling is also present. 

If nnc = 220: ensure that the 
required DD card C0BTPO0T is 
present. 



If nnc = other: 
has occurred. 



an I/O error 



Reschedule the job by 
reinitializing the CJS. 

nnc UNABLE TO WRITE ENDED 
MESSAGE TO CJS. RUN 
TERMINATED. 

Explanation : Same as for 
IKF430. 



S y.s t e m _Ac t i on : 
terminated. 



The run unit is 



Proqra mmer _ Response ; The 
Communication Job Scheduler 
(CJS) must be reinitialized in 
order to resume polling for the 
queues associated with the 
ended job. 

RECEIVE ISSUED WITHOUT NO DATA 
CLAUSE AFTER EGI ON BSAM-MODE 
INPUT QUEUE 

Explanation: An implicit 
request for RECEIVE to wait for 
the next message to enter the 
input queue cannot be satisfied 
for an empty BSAM-raode input 
queue {no additional messages 
can be placed in the queue) . 



System Action : 
terminated. 



The run unit is 



Programmer Response: Provide a 
no data clause for the RECEIVE 
statement, or do not attempt to 
read beyond EGI FOR BSAM-mode 
input queues. 

INVALID SEPARATE SIGN 
CONFIGURATION 

Explanation: The SEPARATE SIGN 
configuration is invalid on the 
data item. 

Programmer Respo nse : Probable 
user error. Correct the 
indicated statement and rerun 
the job. 

If the problem recurs, have the 
following items available 
before calling IBM programming 
support: source deck, control 
cards, and compiler output. 
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IKF888I- UNSUCCESSFUL SORT FOE 
SORT-FILE-DDNAME. 



Explanation: The Operating 
System Sort/Merge program has 
returned a nonzero code to the 
COBOL program and the user has 
not specified the special 
register SORT-RETURN. 



Progr ammer Respo nse: Probable 
user error. Specify the 
special register SORT- RETURN 
and rerun the job; do not 
assume that any portion of the 
sort (input or output 
procedure) has been performed. 



If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 



Opera tor Response: Probable 
user error. User should have 
indicated whether or not the 
job should be canceled. The 
user should not assume that any 
portion of the sort (e.g.. 
Input or Output Procedure) has 
been performed. 



IKF990D- AWAITING REPLY 

Explanatio n: This message is 
generated by an ACCEPT 
statement with the FROM CONSOLE 
option. 

Programmer Responge: Not 
applicable. 

Operator Response: If message 
is unexpected, then probable 
user error. Issue a REPLY 
command. The contents of the 
text field should be supplied 
by the programmer. 
IKF991I- NO STORAGE AVAILABLE FOR 
WORKING STORAGE FOR **** 

Explan atio n: The **** library 
subroutine has insufficient 
work space. 



IKF992I- RECURSIVE CALL TO MODULE FROM 
MODULE ****. 

Explanati on: The module whose 
name is substituted for the 
asterisks in the message text 
has been called recursively. 

System Action : COBOL does 
STOP RUN processing, returning tc 
the original caller of its main 
program. 

Programmer „ Response : Pro babl e 
user error. Correct the 
recursive call situation and 
rerun the job. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF993I NO STORAGE AVILABLE FOR 

GETMAIN. INCREASE REGION SIZE 
AND RE-EXECUTE PROGRAM. 

Ex £l a nation : A library 
subroutine has insufficient 
work space. 

Sj£stem_Action: user ABEND 3440 
will occur. 

Programmer Response : Probable 
user error. Increase the 
region size and re-execute the 
program. 

IKF994I GETMAIN/FREEHAIN REQUEST 

INVALID. PROGRAM EXECUTION 
TERMINATED. 

Explana tion: Library 
subroutine ILBOCMMO has 
received a GETMAIN/FREEMAIN 
reguest from another library 
subroutine that it cannot 
recognize. 

S2sjDem_Action: User ABEND 3440 
will occur. 

Programmer Res ponse: This 
message should not occur. Have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler and 
execution-time output. 



System Action : 
canceled. 



The job is 



Programmer Response: Probable 
user error. Increase the 
region size and re-execute the 

program. 
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IKF999I UNSUCCESSFUL OPEN FOR 

ddname. PROGRAM EXECUTION 
TERMINATED . 

Explanation : The data set 
identified by ddname could 
not be opened to implement 
an ACCEPT statement. 

System Action : The run unit 
is terminated. 

Programmer Response : Probable 
user error. Check for a 
missing or incorrectly-specified 
DD statement. 



Di agnost ic Messages — BC S Cons ide rations 



All console messages issued by this 
compiler or its object code include 
parameters for multiple console support, 
description of these parameters follows: 



3. Compiler console messages (IKF0003I) 
are assigned: 

* a routing cod e of 2/11 (chief 
operator information/write- 
to- prog rammer) 

• a descripto r code of 7 (job status 
message) . 

Each message includes the 
write-to- programmer .parameter ..and uses a 
system message block which then becomes 
unavailable until after the message is 
printed. since a maximum number of these 
system message blocks must be specified by 
the installation's system programmer at the 
time of system generation, it is possible 
for the number of messages requiring system 
message blocks to exceed the number of 
blocks available. If this occurs, the 
programmer is warned of the condition, but 
all succeeding messages are ignored. 



1. DISPLAY statement with the ON CONSOLE 
option (unnumbered) and all object 
time write-to-operator (IKF111I, 
IKF888I, IKF9 99I) messages are 
assigned: 

♦ a routing .c od e of 2,11 {chief 
operator information/write- 
to- programmer) 

* a descriptor code of 7 (job status 
message). 



2. STOP "literal' (IKF000A) and ACCEPT 

statement with the FROM CONSOLE option 
(IKF990D) messages are assigned: 

* a routing code of 2,11 (chief 
operator inf ormation/write- 
to-programmer) 

• a descriptor code of 2 (immediate 
action required) . 



COB OL Object Program Unnu mbered Messages 



XXX.. . 



Explanation : This message is 
written on the console and is 
recognizable because it is not 
preceded by a message code and 
action indicator. It is 
generated by a DISPLAY statement 
with the ON CONSOLE option. The 
message text is supplied by the 
object program and may indicate 
alternative action to be taken. 

System Act ion: The job 
continues. 

Operator Response: Operator 
response, if any is needed, is 
determined by the message text. 
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QUgUE ANALYZES MESSAGES 



The COBOL queue-analyzer subroutine 
generates the messages that follow for the 
error conditions it diagnoses. Like the 
COBOL compiler, the queue analyzer 
sometimes issues warning messages and takes 
corrective action. Other conditions that 
indicate more serious errors result in 
termination of the queue structure 
description program. 

For descriptions of the queue-analyzer 
subroutine and the queue structure 
description program, see the "Programming 
Techniques" part of this publication. 



IKF700I-E 



IKF701I-E 



MEMBER NOT WRITTEN FOE 

PRECEDING QUEUE STRUCTURE DUE 
TO ONE OR MORE ERRORS NOTED 
ABOVE. 

Explanation : This message is 
always accompanied by other 
diagnostics. A partitioned 
data set cannot be created for 
the queue structure described 
because of serious errors. 



System Action: 
not written. 



The member is 



Programmer Res ponse: Probable 
user error, correct the syntax 
and other errors in the program 
before recompiling. 

If the problem recurs, have 
the following available before 
calling IBB for programming 
support: source deck, control 
cards, and compiler output. 

PDS ALREADY CONTAINS MEMBER 
WITH SAME NAME AS THE 
PREVIOUS QUEUE STRUCTURE. 
QUEUE NOT ADDED. 

E xplan ation: Each member of a 
partitioned data set must have 
a unique name. 



IKF702I-E 



IKF703I-W 



IKF704I-E 



support: source deck, control 
cards, and compiler output. 



RAN OUT OF SPACE IN PDS 

DIRECTORY WHILE ATTEMPTING TO 
ADD PRECEDING QUEUE 
STRUCTURE. 

Explanation: There is not 
sufficient space in the 
partitioned data set to add the 
queue structure. 



System ^Action : 
continuing. 



Compilation is 



System A ctio n : 
not added. 



The queue is 



£E23X§Blg£_E®S£0|ise: Probable 
user error. Specify a larger 
value in the SPACE parameter. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

WARNING: QUEUE OR SUB-QUEUE 
NAME EXCEEDS 12 CHARACTERS IN 
LENGTH. FIRST 12 CHARACTERS 
USED AS NAME. 

Ex planat ion: The name of a 
queue or sub-queue name may 
contain a maximum of 12 
characters. 

System Action: The name is 
truncated to 12 characters. 

Programmer Res ponse: Probable 
user error. Substitute for the 
name indicated a queue name or 
sub-queue name that does not 
exceed 12 characters. Then 
recompile the program. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

UNRECOGNIZABLE KEYWORD IN ABOVE 
STATEMENT. STATEMENT 
DISREGARDED. 



Programmer Response: Probable 
user error. Either assign a 
new name to the member being 
added or run the IEHPROGM 
utility program to scratch the 
dd member from the PDS; then 
rerun ILBOQSUO. 

If the problem recurs, have 
the following available before 
calling IBM for programming 



Explanation: The source 
statement immediately 
preceeding this error message 
contains at least one 
unrecognizable word. 

System Action: The statement 
is discarded. 

Programmer Re spo nse: Probable 
user error. Recode the 
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IKF705I-E 



IKF706I-W 



IKF707I-E 



statement indicated and rerun 
the job. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source dack, control 
cards, and compiler output. 

ONE OR MORE KEYWORDS OMITTED IN 
ABOVE STATEMENT. STATEMENT 
DISCARDED. 

Explanation: Each sub-gueue 
level must contain a reference 
to the sub-gueue to be defined, 
the verb "IS", and the name to 
be assigned to the sub-gueue. 



S ystem Action : 
is discarded. 



The statement 



Programme r Resp onse: Probable 
user error. Correct the source 
statement indicated before 
recompiling. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

WARNING: QUEUE OR SUB-QUEUE 
NAME IS LESS THAN 12 
CHARACTERS IN LENGTH AND ENDS 
IN COLUMN 80. ACCEPTED AS 
WRITTEN. 

Expla n atio n: The gueue or 
sub-gueue name ends in the 80th 
position in the record. 

Sy stem Action: The statement 
is accepted as written. 

Progr ammer Response: Verify 
that the gueue name or 
sub-gueue name is complete 
before recompiling. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

SUB-QUEUE LEVEL NUMBER IN ABOVE 
STATEMENT IS NOT 1, 2, OR 3. 
STATEMENT DISCARDED. 

Explanation: A gueue structure 
must contain one, two, or three 
levels of sub-gueues, written 
SUB-QUEUE- 1, -2, or -3. 



Programmer Response: Probable 
user error. Substitute for the 
sub-gueue level number 
indicated the numeral *1», '2', 
or *3*, as appropriate. 



If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 



IKF708I-E MORE THAN 200 STATEMENTS IN 
PRECEDING QUEUE STRUCTURE. 
SKIPPING TO NEXT QUEUE 
STRUCTURE OR END OF INPUT. 



Explanation: A gueue structure 
may not contain more than 200 
statements. 



Sy s tem A ction: The gueue 
structure was not created. 

Pro gramme r Response: Probable 
user error. Recode the gueue 
and sub-gueue definition 
statements not to exceed a 
maximum of 200. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF709I-E ONE OR MORE LEVELS MISSING 
BETWEEN LEVEL IN ABOVE 
STATEMENT AND LEVEL DEFINED 
IN PRECEDING STATEMENT. 

Explanat ion: When a lower 
level of the sub-gueue 
hierarchy is described, ' all 
higher levels in that leg of 
the structure must be 
specified. For example, a 
SUB-QUEUE-3 statement cannot 
immediately follow a 
SUB-QUEUE- 1 statement. 



System Action: 
is discarded. 



The statement 



System Action: 
is discarded. 



The statement 



Programmer Response: Probable 
user error. Supply the 
additional reguired sub-gueues 
before recompiling. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 
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IKF710I-E FIRST CONTROL STATEMENT DOES 
NOT DEFINE A QUEUE-LEVEL 
NAME. SKIPPING TO FIRST 
"QUEUE IS" STATEMENT. 

Explanation: The first 

statement in the queue IKF713I-E 

structure description must 

specify a queue definition. 



Slstea_Action: The compiler is 
skipping to the first queue 
definition. 



Programmer Response: Probable 
user error. Rewrite the source 
statement (s) indicated so that 
the first control statement 
defines a queue- level name. 
Then recompile the program. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF711I-E DDNAME IN ABOVE STATEMENT NOT 
COMPLETED AT END OF 80 
CHARACTERS. STATEMENT 
DISCARDED. 

Expla nat ion: A ddname in the IKF714I-E 

statement indicated cannot 
contain more than 80 
characters. 

System Ac tion: The statement 
is discarded. 



If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

A DDNAME IS SPECIFIED IN THE 
SECOND STATEMENT ABOVE, BUT 
THIS IS NOT A LOWEST-LEVEL 
SUB-QUEUE IN THE STRUCTURE. 

S^ElsLaa t i on : At execution 
time, the partitioned data set 
is described on a DD card, and 
the message control program 
table entries and the 
lowest-level sub-queue names 
are linked by DD cards. 



System Action: 
is discarded. 



The statement 



Program mer Res ponse: Probable 
user error. Substitute for the 
invalid ddname indicated a name 
that matches a lowest-level 
sub-queue. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

DDNAME IN ABOVE STATEMENT 
BEGINS WITH A NUMBER. 
INVALID IN OS. 

ILX2ii.I3Lil.ti2n. : In OS a ddname 
must begin with an alphabetic 
character. 



IKF712I-E 



Pro gra mmer Response: Probable 
user error. Replace the ddname 
indicated with one of the 
required length. Then 
recompile the program. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

DDNAME IN ABOVE STATEMENT 
EXCEEDS 8 CHARACTERS IN 
LENGTH. STATEMENT DISCARDED. 

Explanation: A ddname cannot 
exceed 8 characters in length. 



System Action: 
is discarded. 



The statement 



Programm er Respo nse: Probable 
user error. Substitute for the 
ddname indicated one that does 
not exceed 8 characters. 



IKF715I-D 



Sy.stem_Action: The statement 
is discarded. 

Programmer. Response : Probable 
user error. Substitute for the 
invalid ddname one whose first 
character is alphabetic. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

UNABLE TO RUN COBOL QUEUE 
UTILITY DUE TO LACK OF 
SUFFICIENT CORE AVAILABLE. 
RERUN WITH LARGER REGION 
SIZE. 

Explanation : There is not 
sufficient space to run the 
queue utility program. 



System Action : 
terminated. 



The run is 
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IKF716I-D 



Progra mm er Respons e: Probable 
user error. Specify a larger 
size in the REGION parameter. 

If the problem recurs, have 
the following available before 
calling IBM for programing 
support: source deck, control 
cards, and compiler output. 

ERROR OCCURRED DURING OPENING 
QUEUE-STRUCTURE DATA SET. 
RUN TERMINATED. 

Explanation: The DD card for 
the COBTPQD data set is either 
missing or incorrect. 



System Actio n : 
terminated. 



The run is 



IKF717I-D 



Progra mmer^ „ Response: Probable 
user error. Check for a valid 
COBTPQD DD card before 
recompiling. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

ERROR OCCURRED OPENING SYSIN 
DATA SET. RUN TERMINATED. 



calling IBM for programming 
support: source deck, control 
cards, and compiler output. 



IKF718I-E THE NAME ***** APPEARS MORE 

THAN ONCE AT THE SAME LEVEL 
IN A SINGLE LEG OF THE 
CURRENT STRUCTURE. 



Explanation : Each queue or 
sub-queue defined for a queue 
structure must be unique. 



System Action: The statement 
is discarded. 

EESSSammer^Res^onse: Probable 
user error. Rewrite the queue 
or sub-queue name indicated so 
that it is unique. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 

IKF719I-E THE NAME **** AT SUB-QUEUE 
LEVEL **** IS SUPERFLUOUS 
SINCE THIS IS THE ONLY NAME 
AT THIS LEVEL. 



Explanation: Because the DD 
card for the SYSIN data set is 
either missing or incorrect, 
the SYSIN data set cannot be 
opened. The program cannot be 
compiled. 



System Action: 
terminated. 



The run is 



Progr ammer Response: Probable 
user error, check for a valid 
SYSIN DD card before 
recompiling. 

If the problem recurs, have 
the following available before 



Explanation: The sub-queue 
name at level **** is the only 
name at this level. 

System^ Action: The statement 
is discarded. 

Program mer Re sponse: Probable 
user error. Check the queue 
structure for a one-legged path 
before recompiling. 

If the problem recurs, have 
the following available before 
calling IBM for programming 
support: source deck, control 
cards, and compiler output. 
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APPENDIX L: RESOLVING CpBQL CpMPILEB PROBLEMS 



When a user encounters problems with the 
COBOL compiler or LCP, he should gather as 
much as possible of the following 
inforaation before presenting the problem 
to the FE to get the problem resolved in 
the fastest possible way. 



• Source deck — it is imperative that a 
source deck {or tape containing the 
source program) be supplied with any 
reported problem. 

• COPY and BASIS libraries (if needed) 

• Compilation listing (PHAP, DMAP, SXREF 
preferably) 

• Abend listing (if necessary) 

• Compiler options 

• SIZE, BOF 

• Compiler work file allocations 

• Block sizes for compiler files 



Region/partition size 

System level and environment 

Type of hardware used 

PTFs applied to system 

PTFs applied to product 

ZAPs applied to product 

Any local fixes/changes made to product 

Any bypasses 

Does problem always occur or is it 
intermittent? 

If compiler failure — number of phase in 
which failure occurred (this can be 
obtained from first page of SYSUDUMP 
listing) 

If execution problem - any files used 
by the object program that would be 
needed to re-create the problem should 
be supplied when the problem is 
reported. 
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APPERpiX M; 3886 OPTICAL CHARACTER READER PROCESSING 



The 3886 Optical 
1* {herein referred 
general purpose onli 
satisfies a broad ra 
requirements. The 
from 3x3 inches to 9 
can read raachine-pri 
numeric and certain 
wide variety of font 
hand-printed numeric 



Character Header, Modal 
to as "OCR") , is a 
ne device that 
nge of data entry 
CB accepts documents 
x12 inches in size. It 
nted alphabetic, 
special characters in a 
s, as well as 
characters. 



The OCR reads documents one line at a 
time, under program control. Additional 
facilities, all under program control, 
include; document marking, line marking, 
document eject <with stacker selection, and 
line reread (for the current line, and with 
a different format description, if 
desired) . (It is important in designing 
documents to remember that the OCR cannot 
reread previous lines; reading can only 
proceed from top to bottom on the 
document.) 



The use of this appendix requires 
familiarity with the publications: 



* IBM 3886 Optical Character Reader 
General Information Manual, Order 
No. GA21-9146. 

* IB3 3886 Optical .Charact er Reade r In put 
Document Design Guide and 

Seecif ications Manual , r d er 
No7 GA21-9U8. 

In addition, the relevant portions of 
the following manuals should be referenced: 

* QS/VS1 System m Generation Reference. 
Order No. GC26-3791. 

* OS/ysg^System^Ge ne ration, Reference, 
Order~No. GC26-3792. 

* OS/VS Program Planning Guide for IBM 
3886 Optical Char ac ter Reade r Mod el 1 , 
Order No. GC21-5069. 

* OS/YS Data Managem en t. Services Guide, 
Order No. GC 26- 3 73 3. 



♦This device should not be confused with 
the 3336, Model 2, which is an offline 
Optical Character Reader, with output to 
tape. Information is included in this 
appendix, however, to help in processing 
tapes produced by the Model 2 



OCR COBOL CAPABILITIES 

The COBOL user can request nine 
different I/O operations with the OCR as 
follows: 

• OPEN - Open a 3886 data set. 

• CLOSE - Close a 3886 data set. 

• READ - Read a line on a 3886 document. 

• READO - Read a line on a 3886 document. 
READO must be followed by a WAIT. 

• WAIT - Wait for completion of READO. 

• SETDEV - Load the format record. 

• MARKL - Mark a line. 

• MARKD - Mark the current document. 

• EJECT - Eject the current document. 

OCR I/O REQUESTS 



The I/O requests listed above cannot be 
issued directly; instead, the COBOL 
programmer must place the desired request 
in a COBOL data area of a specified format 
and then pass this information to a 
subroutine by a CALL statement with the 
USING option. The called subroutine 
handles the request and returns any 
requested information as well as certain 
additional information in case of an error. 
The CALL can have only the one parameter 
just described following the USING; if more 
than one is specified, the subroutine will 
return control immediately to the user with 
a value of 8 in the RETURN-CODE special 
register. 

Figure 190 describes the necessary 
format of the COBOL data area that is 
passed to the subroutine. The data-name 
symbols used in Figure 190 are used for 
illustrative purposes only; any valid COBOL 
data-name symbols may be used. The 
data-name symbols used in Figure 186 
describe the use of the fields in the 
parameter. To assist the user, an 
IBM- supplied source member, ILBOOCRD, can 
be included in the Data Division of the 
user program via a COPY statement. The 
contents of ILBOOCRD are listed in Figure 
191. Another IBM-supplied source member, 



5HH 



ILBOOCRP, can be included in the Procedure 
Division via a COPY statement. ILBOOCRP, 
the contents of which are listed in Figure 
192, can be used for doing OCR operations. 



indicate whether or not the operation was 
successful. This indicator is placed in 
bytes 22-23 of the data area passed to the 
subroutine. The possible cause, meanings, 
and programmer response to each value are 
listed in Figure 193. 



OCR STATUS KEY 



After each operation, a status indicator 
is passed back to the COBOL program to 



JDATA DIVISION Entry 



01 OCR- FILE. 

02 OCR-FILE-ID PIC X (8) VALUE «dd 
02 OCR-FORMAT-RECORD-ID PIC X (8) 
» DFR phase name*. 



02 OCR-OPERATION PIC X (5) . 

02 OCR-STATUS- KEY PIC 99. 
02 OCR-LINE-NUMBER PIC 99. 

02 OCR-LINE- FOR MAT PIC 99. 

02 OCR-MARK PIC 99. 

02 OCR-STACKER PIC 9. 

02 OCR-HEADER-RECORD PIC X(20) 

02 OCR-DATA-RECORD PIC X{130). 



I Comments 
H 



f 

name' . } 
VALUEJ Format record name used 
JPhase name is FRLGxxxx, 
J characters are used; if 
JFRID on dd statement is 
J Can be set to OPEN, CLOS 
JSETDV, MARKL, MARKD, or 
| Also referred to as exce 
ILine no. (0-33) passed 
| EJECT. 

J Line format no. (0-6 3) 
jMark option (1-15) passe 
JPocket no. (1-2) passed 
| Header information retur 
J WAIT. 
JData record returned fro 

, 1 



for OPEN or SETDEV. 

where only the last 4 

blank during OPEN, 

used. 

E, READ, READO, WAIT, 

EJECT. 

ption code. 

to MARKL, READ, or 

passed to READ. 

d to MARKL or MARKD. 

to EJECT. 
ned from READ or 

m READ or WAIT. 



Figure 190. Format of COBOL Parameter Data Area 
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VALUE 


*DDNN3886«. 


VALUE 


•FRLGDFR1 1 . 


VALUE 


•OPEN ». 


VALUE 


•OPEN •. 


VALUE 


'CLOSE'. 


VALUE 


•READ ». 


VALUE 


«READO». 


VALUE 


•WAIT 1 . 


VALUE 


•MARKL*. 


VALUE 


•MARKD 1 . 


VALUE 


•EJECT ». 


VALUE 


•SETDV». 


VALUE 


0. 



************************* ILBOOCRD - OCR DATA DESCRIPTION ***************************** 
*************************************************************************************** 
************************ OCR 3886 FILE FORMAT ************************ 
*************************************************************************************** 

01 OCR-FILE. 

05 OCR-FILE-CONTROL-AREA. 

10 OCR-FILE-ID PIC X (8) 

10 OCR-FORM AT- RECORD- ID PIC X (8) 

10 OCR-OPERATION PIC X(5) 

88 OCRO-OPEN 

88 OCRO-CLOSE 

88 OCRO-READ 

8 8 OCRO-RE AD-OVERLAPPED 

88 OCRO-tfAIT 

88 OCRO-HARK-LINE 

88 OCRQ-MARK-DOCUMENT 

88 OCRO- EJECT 

8 8 OCRO-SETDEV 
10 OCR-STATUS-KEY PIC 99 

* (STATUS KEY CODES AND NAHES TO BE CHANGED) 

88 OCRS-SUCCESSFUL 

8 8 OCRS- EN D-OF- FILE 

88 OCRS-IO-ERRORS 

88 OCRS-MISC-ERROR 

88 OCRS-MARK-CHECK 

88 OCRS-NONRECOVERY-ERROR 

88 OCRS-INCOMPLETE-SCAN 

88 OCRS- MARK -AND-EQUIP-CHECK 

88 OCRS-PERMANENT-ERROR 

88 OCRS-SPECIAL-ERRORS 

88 OCRS-LOGIC-ERROR 

88 OCRS- RESOURCE-UNAVAILABLE 

88 OCRS-INVALID-PARAMETER 

8 8 OCRS-INVALID- OPERATION 

OCR-LINE. 

15 OCR-LINE- NUMBER PIC 99 

15 OCR-LINE-FORMAT PIC 99 

OCR-MARK PIC 99 

OCR-STACKER PIC 9 



10 



10 
10 



VALUE 00. 

VALUE 10. 

VALUE 30 THRU 39, 

VALUE 30. 

VALUE 31. 
VALUE 32. 
VALUE 33. 
VALUE 34. 
VALUE 39. 
VALUE 90 THRU 99. 
VALUE 92. 
VALUE 93. 
VALUE 95. 
VALUE 99. 

VALUE 1. 

VALUE 1. 

VALUE 0. 

VALUE 1. 



Figure 191. IBM-supplied Data Division COPY Member (Part 1 of 2) 
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******* HEADER AND DATA RECORD AREAS******* 
PILLED IN BY SUCCESSFUL 'READ' AND/OR •gAIT*. 
(NOTE - «READO' DOES NOT ALTER THESE AREAS) 



OCR-HEADER-RECORD 
10 ORCH- LINE-NUMBER PIC 99. 

10 ORCH-LINE-FORMAT PIC 99. 

10 ORCH-LINE-SCAN-COUNT PIC 9. 

10 OSCH-LINE-STATUS PIC 9. 

88 ORCH- LINE -GOOD 
88 ORCH-LINE-BLANK 
88 ORCH-LINE-GROUP-ERASE 
88 ORCH-LINE-CRITICAL-ERR 
88 ORCH-LINE-NON-CRITICAL-ERR 
88 ORCH-LINE-COMBINED-ERR 
88 ORCH-LINE-INVALID 
88 ORCH-END-OF-PAGE 
10 ORCH-FIELD-INFO. 

15 ORCH-FILED-STATUS PIC 9. 

88 ORCH- FIELD-GOOD 
88 ORCH-FIELD-REJECT-CHARS 
88 ORCH-FIELD-WRONG-LENGTH 
88 ORCH-FIELD-CQMBINED-ERR 
88 ORCH-FIELD-BLANK 
88 ORCH-FI ELD-BLANK-SUP 
05 OCR -DAT A- RECORD. 

10 OCR-STANDARD-MODE-RECORD. 

15 OCR-STANDARD-FIELD-CHAR PIC X 
10 OCR-IMAGE-MODE- RECORD 

REDEFINES OCR-STANDARD-MODE-RECORD. 
15 OCR-IMAGE-FIELD-LENGTH PIC 99 

15 OCR-IMAGE-FIELD-CHAR PIC X 

************ END p 3886 DATA DIVISION COPY MEMBE 



VALUE ZEROS. 



VALUE 0. 

VALUE 1. 

VALUE 3. 

VALUE 2. 

VALUE 4. 

VALUE 6. 

VALUE 7. 

VALUE 5. 

OCCURS 14, 

VALUE 0. 

VALUE 2. 

VALUE 4. 

VALUE 6. 

VALUE 8. 

VALUE 4. 



OCCURS 130. 



OCCURS 14. 

OCCURS 102, 
g ************ 



Figure 191. IBM-supplied Data Division COPY Member (Part 2 of 2) 
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t 

j******* iiBOOCRP - OCR 3886 PROCEDURES 

j ******* OCR 3886 PROCEDURES ******* 

j ****** ******************** ***** *********************************************** ********* 

J* THE 3886 OCR SUBROUTINE USES OCR-FILE FIELDS AS FOLLOWS 

t* 

!* ALL OPERATIONS REQUIRE 

{* OCR-FILE-ID = THE UNIQUE NAME USED TO IDENTIFY THE FILE 

|* TO THE SUBROUTINE AND TO THE SYSTEM 

|* OCR-OPERATION = THE CODE FOR THE REQUESTED OPERATION 

|* ALL OPERATIONS RETURN 

f* OCR-STATUS-KEY = RETURN CODE FOR VARIOUS OCCURRENCES 

I* 

i* OCR-OPEN ('OPEN ') ALSO REQUIRES 

j* OCR-FORMAT- RECORD-ID = LIBRARY NAME OF DFR TO LOAD 

}* OCR-READ («READ ') ALSO REQUIRES 

J* OCR-LINE-NUMBER (1-33) = LINE TO READ (ON DOCUMENT) 

1* OCR-LINE-FORMAT (1-63) = DLINT NUMBER (IN CURRENT DFR) 

|* AND RETURNS (IF OCRS-SUCCESSFUL) 

J OCR-HEADER-RECORD = HEADER RECORD, AS RETURNED BY THE 3886 

I* OCR-RECOGNITIGN-RECORD = DATA FROM DOCUMENT, FROM 3886 

J* OCR-READ-OVERLAPPED ('READO') HAS SAME REQUIREMENTS AS OCR-READ 

J* OCR-HAIT(» WAIT ') RETURNS SAME PARAMETERS AS OCR-READ 

|* OCR-MARK-LINE ('MARKL') ALSO REQUIRES 

|* OCR- LINE-NUMBER (1-33) = LINE TO MARK (ON DOCUMENT) 

|* OCR-MARK (1-15) = SUM OF DESIRED MARK CODES (8421) 

,* 

J* OCR-MARK-DOCUMENT (' MARKD* ) ALSO REQUIRES 

|* OCR-MARK (1-15) = SUM OF DESIRED MARK CODES (8421) 

j* OCR-EJECT ('EJECT') ALSO REQUIRES 

J* OCR-POCKET (1-2) = STACKER TO SELECT (A OR B) 

|* OCR-LINE-NUMBER (0-33) = NUMBER OF LINES ON DOCUMENT 

J* FOR VALIDATION (IF 0, NO VALIDATION WILL OCCUR) 

|* OCR-SET-DEVICE ('SETDV') ALSO REQUIRES 

|* OCR-FORMAT- RECORD-ID = LIBRARY NAME OF OFR TO LOAD 

I* 

J*NOTES 

|* 1. THE TERMS DFR AND DLINT ARE USED TO REFER TO THE EXPANDED 

|* CODE, IN LOADABLE FORM, OF THE RESPECTIVE SYSTEM MACROS. 

|* 2. OCR-WAIT MAY BE REQUESTED AFTER, AND ONLY AFTER, A 

|* SUCCESSFUL OCR-READ-OVERLAPPED REQUEST. NO INTERVENING 

J* I/O COMMANDS WILL BE ALLOWED ON THAT SAME FILE. 

|* 3. THE PROCEDURES PROVIDED BELOW AUTOMATICALLY FILL IN 

i* THE OCR-OPERATION FIELD, CALL THE SUBROUTINE, AND TEST 

1* THE GCR-STATUS-KEY AFTER RETURN. IF ANY EXCEPTIONAL 

J* CONDITIONS OCCUR, THEY PASS CONTROL TO THE ROUTINE 

1* OCR-EXCEPTION-ROUTINE, WHICH THE PROGRAMMER MUST PROVIDE. 

J* THE PROGRAMMER HAY AVOID EXCEPTION ROUTINE INVOCATION BY 

1* ADDING THE FOLLOWING PHRASE TO THE COPY STATEMENT: 

J* REPLACING OCR-EXCEPTION-ROUTINE BY OCR-CALL-EXIT 

J* 4. ALTHOUGH OCR-STATUS-KEY MAY INDICATE THAT THE DESIRED OPERATION 

1* WAS UNSUCCESSFUL, THE VALIDITY OF THE DATA OBTAINED SHOULD 

|* BE DETERMINED BY TESTING OCRH-LINE-STATUS 

I*************************************************************************************** 

i : , 

Figure 192. IBM-supplied Procedure Division COPY Member (Part 1 of 2) 
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OCR-3886- PROCEDURES. 
OCR-OPEN- 
MOVE 'OPEN » TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 
OCR-CLOSE. 

MOVE 'CLOSE' TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 
OCR-READ. 

MOVE 'READ ' TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 
OCR-READ-OVERLAPPED. 

MOVE «READO» TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 
OCR-WAIT. 

MOVE 'WAIT' TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR- CALL-EXIT. 
OCR-MARK-LINE. 

MOVE 'MARKL' TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 
OCR-MARK- DOCUMENT. 

MOVE 'MARKD' TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 
OCR-EJECT. 

MOVE 'EJECT' TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 
OCR-SET-DEVICE. 

HOVE 'SETDV TO OCR-OPERATION OF OCR-FILE. 

PERFORM OCR-CALL THRU OCR-CALL-EXIT. 
OCR-CALL. 

CALL MLBDOCRO' USING OCR-FILE. 

IF NOT OCRS-SUCCESSFUL OF OCR-FILE. 
GO TO OCR-EXCEPTION-ROUTINE. 
OCR -CALL-EX IT. EXIT. 
********** ESD OF 3886 PROCEDURE DIVISION COPY MEMBER********** 

Figure 192. IBM-supplied Procedure Division COPY Member (Part 2 of 2) 



IMPLEMENTING AN OCR APPLICATION 



DOCUMENT DESIGN 



Design and coding of the OCR aspects of 
an application aay be accomplished in COBOL 
as follows: 

1. Document design - prepare the OCR form 
that Mill be used for input, 
independently of the COBOL program. 

2. Document description - code the DFR 
and DLINT macros to be used in reading 
the document (s) , independently of the 
COBOL program. 

3. COBOL file and record descriptions - 
code the COBOL data structures that 
correspond to the DLINT macros defined 
earlier. They should be defined as 
subordinate to the OCR-FILE area, 
vhich the programmer may COPY into the 
source program. 

4. COBOL procedural code - code the COBOL 
source statements required to control 
the file, read lines, and recover from 
errors. COBOL provides a COPY member 
to simplify this file handling. 



Document design criteria are given in 
detail in the IBM 388 6 Optical Character 
Reader , Input Document Design Guide and 
Specificat i ons . The most important aspects 
of document design are: 

1. The location of lines which can be 

read. These are identified by "timing 
marks"; lines not associated with 
timing marks are always ignored by the 
OCR. Note that lines may be almost 
anywhere on the document, and need not 
be at regular intervals. 

2. The location of fields to be read, 
"Fields," strings of related 
characters, should be identified in 
document design. They will eventually 
required description, using the DFR 
and DLINT macros (see "Document 
Description") . 

3. The form identifier. This field 

should be a pre-printed code, useful 
for identifying one of many different 
forms. It should be at a common 
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location on the first 
of each form. (This 
course, be ignored by 
DLINT specification i 
should, however, be i 
form design, so as to 
form changes or addit 
forms without disrupt 
operations.) 



(readable) line 
field can, of 

programming or 
f desired; it 
ncluded in the 

allow for later 
ional batched 
ion of 



The DFR macro identifies, by name, a 
collection of DLINT macros, and establishes 
various default field scanning options for 
them. As such, it is intended that each 
different DFR grouping will identify a 
different document, or a largely different 
way of scanning the same document (e.g., 
when typed entirely in a different font) . 



DOCUMENT DESCRIPTION 



Documents are described in the system 
with the DFH (Define Format Records) and 
DLINT (Define Line Type) macros. 



DFR and DLINT macros, after assembly and 
linkage editing, are preserved in loadable 
form until called for by the application 
program. 



Status Key 
Value 



Operations Causing 
Value 



Meaning 



Programmer Response 



00 



Any OCR I/O 



J Successful 



J Continue processing normally. 



10 



READ, WAIT, MARKL, JEnd-of-file | 

MARKD, EJECT, SETDEVJ Close file. J 



Do end of file processing. 
See Note 1. 



_j 

| See Note 1. 
I 



30 



OPEN 



J Miscellaneous 
J error 
-I 



31 



EJECT 



JMark Check 
i 



J Attempt to re-read the line, or 
} eject document and prepare to 
J process the next document. 



32 



Any OCR I/O except jNon- recovery 
OPEN and CLOSE j error 

+ 



Eject the document and prepare to 
process the next document. 



+ 



33 



READ, WAIT 



J Incomplete scan j 
1 I 



4- 



Re-read the line using either a 
different DLINT or an image-mode 
DFR. 



34 



EJECT 



JMark Check and 
lEguipment Check 



| See Note 2. 
I 



Notes 



End-of-file occurs on the listed I/O commands when the operator has pressed the 
END-OF-FILE button, no documents remain in the read station, and no errors are 
outstanding. (EOF might also occur on OPEN but only following some unusual 
operator actions.) If the file is DD DUMMY, EOF is given only on READ and WAIT 
commands, commands are checked for validity but no physical I/O requests are 
issued. 

The noted errors represent serious I/O error conditions. No more I/O should be 
performed on the device after any of these errors are encountered. The program 
should, in general, indicate the error, do clean-up, and issue a STOP RUN. 

The noted errors represent a serious programming error or a problem in the program 
environment. The program should indicate the error, do clean-up, and issue a STOP 
RUN. 



Additional Note; 



WAIT and READ commands return data and header records only for the 
following codes; 00 (successful) , 10 (EOF - if not a dummy file) , 31 
(mark check) , and 33 (incomplete scan) . For any other copies, the 
contents of the header and data record areas are unpredictable. 



Figure 193. OCR STATUS KEY Values (Part 1 of 2) 
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r r — . ^ , , 

I Status Key| Operations Causing II 1 
| Value | Value ] Meaning ] Programmer Response \ 
ii i i f 


it i i ~ i 

I 39 1 Any OCR I/O except | Permanent error | See Note 2. This code indicates one| 
| JOPEN and CLOSE J | of the following errors: Command | 

II 1 | Reject, Bus out check. Equipment j 
1) 1 1 Check, Non-initialized, RCP error, | 
|| | | or Invalid Format. I 
ii i i , i 


11 I l f 

| 92 1 Any OCR I/O JLogic error | See Note 3. This code represents an| 
II | | error in operation order: | 

I | | | , • OPEN issued on file already open.] 
|| | | • Pile not open (all operations j 
|| I j except OPEN) . 1 
|| | | * WAIT issued but no READO in | 
|| | | progress. I 

II | 1 • READO followed by an operation J 
|| | | other than WAIT. 1 
it i i f 


ii i i l 

| 93 J OPEN {Insufficient | See Note 3. This code indicates | 
| | | storage |that a GETMAIN issued by the COBOL | 
| | J j subroutine failed. The programmer J 
| | | | should make certain that the REGION 1 
| ] I | parameter specifies enough storage. | 
i .„ , i 1 i i * 


II l i 1 

I 95 JREAD, READO, MARKL, JXnvalid Parameter! See Note 3. A parameter (except | 
| | MASKD, EJECT | JOCR-OPERATION) required by the last | 
I | | | operation was invalid: too large or | 
| | t Jsaall, or contained invalid | 
I 1 I J characters. I 
ii i t i 


ii i i i 

I 99 |No OCR I/O | Unrecognizable | See Note 3. The OCR-OPERATION | 
| | | operation | parameter contained an illegal | 
1 | J | operation code. | 

1 • * i , , , t 


1 Notes: 1 


|1. End-of-file occurs on the listed I/O commands when the operator has pressed the j 
| END-OF-FILE button, no documents remain in the read station, and no errors are | 
| outstanding. (EOF might also occur on OPEN but only following some unusual 1 
j operator actions.) If the file is DD DUMMY, EOF is given only on READ and WAIT | 
| commands. Commands are checked for validity but no physical I/O requests are | 
| issued. 1 

I 2. The noted errors represent serious I/O error conditions. No more I/O should be j 
| performed on the device after any of these errors are encountered. The program | 
| should, in general, indicate the error, do clean-up, and issue a STOP RON. j 

|3. The noted errors represent a serious programming error or a problem in the program | 
| environment. The program should indicate the error, do clean-up, and issue a STOP 1 
1 RUN. I 

| Additional Note: WAIT and READ commands return data and header records only for the I 
| following codes: 00 (successful), 10 (EOF - if not a dummy file), 31| 
| (mark check), and 33 (incomplete scan). For any other copies, the | 
| contents of the header and data record areas are unpredictable. | 



Figure 193. OCR STATUS KEY Values (Part 2 of 2) 



Each DLINT macro describes the scanning 
of a line, by field, in terms of: the 
starting and ending points of fields on a 
line (in tenths of an inch) ; the field 
lengths (in characters) ; the font code to 
be used (OCR-A, OCR-B, Gothic, or 
hand-printed numerics, all with various add 



special character suppression) ; field 
character delimiters (a character to end a 
field scan) ; and various additional 
options. 

Note that the DLINT macro may specify 
either "standard mode" or "image mode." 
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Instandard mode, all DLI 
valid, and the data reco 
format,' according to the 
characters. In image mo 
length and all EDIT keyw 
the data record begins w 
length parameters, indie 
the fields that follow, 
variable format in the d 
mode should be used only 
for which standard mode 



NT options are 
rd is of a fixed 

field lengths in 
de, the field 
ords are invalid; 
ith 14 2-byte 
ating the length of 

Because of this 
ata record, image 

in applications 
is unsuitable. 



cases for which standard mode is 
unsuitable. 

The programmer may describe the data 
records to be read by the application 
program by following the Data Division COPY 
request with the statement: "05 dataname 
REDEFINES OCR-DATA-RECORD. " and starting 
the structure of each record description 
with a level number greater than 5 (see 
Figure 198 for an example). 



COBOL FILE AND RECORD DESCRIPTIONS 



PROCEDURAL CODE 



The file to be processed must be 
described in the Data Division according to 
the format in Figure 190 or the programmer 
may conveniently use the IBM-supplied Data 
Division COPY member (see Figure 191). In 
the IBM-supplied COPY member, all fields 
and codes are included, along with 
descriptive names and default values. The 
programmer need modify only those fields 
that are not appropriate for the particular 
application. 



The file 
COPY member) 
programmer m 
the OCR-STAT 
subprogram, 
haader and d 
by the devic 
data records 
program cont 
reading, and 
described in 
manual.) 

The COBOL 
on the DLINT 
or standard 
standard mod 
returned in 
DLINT: fiel 
right in the 
specified le 
specifies im 
field length 
of the data 
location wit 
of this, ima 



description ("OCR-FILE" in the 

includes all fields that the 
ust provide to the subprogram, 
US-KEY returned by the 
and fields that describe the 
ata records returned directly 
e. (Note that the header and 

are not constructed under 
rol; they are not altered after 
thus their contents are fully 
the General Information 



^record desc 
formats, ei 
mode. If th 
e scanning, 
a fixed form 
ds contiguou 
same order, 
ngth in byte 
age mode sea 
s are return 
record, and 
hin the data 
ge mode shou 



riptions are based 
ther in image mode 
e macro specifies 
the data record is 
at according to the 
s, from left to 

each with a 
s. If the macro 
nning, however, the 
ed at the beginning 
fields vary in 

record. Because 
Id be used only in 



The 3886 file is processed by using CALL 
statements to the IBM-supplied routine 
ILBOOCR0 or by including the IBM-supplied 
Procedure Division COPY member ILBOOCRP. 

ILBOOCRP (see Figure 192 for contents) 
provides paragraphs to perform, which set 
the appropriate operation code, CALL the 
subroutine ILBOOCR0, and passes control to 
a programmer supplied OCR-EXCEPTION routine 
if an exception occurs. 

In general, the programmer must move 
parameter information to the file area 
(OCR-FILE) , and then issue a PERFORM for 
the appropriate procedure. Figure 194 
lists the permissible I/O requests and the 
fields that must be set before issuing the 
CALL; also included are the fields that 
receive information back from the 
subroutine upon completion of the request. 



Exception Handling with IL BOOCRP 



If an exception occurs, the COPY member 
passes control to the procedure-name 
OCR-EXCEPTION-ROUTINE. If operations are 
to be retained in this routine, the 
programmer should do so by using the CALL 
statement directly, and testing the 
OCR-STATOS-KEY value afterwards. Return 
from the OCR-EXCEPTION-ROUTINE would 
normally be to OCR-CALL-EXIT (after a 
successful retry or recovery) . This will 
return control to the invoking PERFORM. 
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t J ^ 

I Function \ Using Identifier \ Set By User 



T ■ 1 

Subroutine Returns J 



OPEN 



0C8-FILE 



OCR-FILE 

OCR-OPERATION 

OCR- FORM AT-RECOHD-ID 



OCR-STATUS-KEY 



CLOSE 



OCR-FILE 



OCR-FILE-ID 
OCR-OPERATION 



OCR-STATUS-KEY 



READ 



OCR- FILE 



OCR-FILE-ID 
OCR-OPERATION 
OCR-LINE-NUMBER 
OCR-LINE-FOSMAT 



OCR-STATUS-KEY 

OCR-HEADER-RECORD 

OCR-DATA-RECORD 



H 



READO 



OCR-FILE 



OCR-FILE-ID 
OCR-OPERATION 
OCR-LINE-NUMBER 
OCR-LINE-FORMAT 



OCR-STATUS-KEY 



WAIT 



OCR-FILE 



OCR-FILE-ID 
OCR- OPERATION 



OCR-STATUS-KEY 
OCR-H EADER-RECORD 
OCR-DATA-RECORD 



—I 



MARKL 
MARKD 
REJECT 



OCR-FILE 



OCR-FILE-ID 
OCR-OPERATION 
OCR-LINE-NUMBER (MAR 
OCR-MARK (MARKL or M 
OCR-STACKER (EJECT) 



OCR-STATUS-KEY 



KL or EJECT) 
ARKD) 



SETDEV 



OCR-FILE 



OCR-FILE-ID 

OCR- FORMAT-RECORD 

OCR-FORMAT-RECORD- ID 



OCR-STATUS-KEY 



1. READ combines the functions of READO and WAIT. 
the issuing task. 

2. A successful READO must be followed by a WAIT r 
Intervening I/O operations for that file are no 

3- The WAIT function causes the active task to be 
necessary, until the preceding READO request is 
immediately following READO. 



I/O overlap is not permitted within 

equest for that same OCR-FILE area. 
t permitted. 

placed in the wait condition, if 
completed. The WAIT must be issued 



Figure 194. Requesting OCR Functions and Information Returned 



SAMPLE PROGRAM 



The sample program that follows consists 
of the document to be processed, the JCL to 
process the DFR and DLINT macro code, the 
COBOL source program, and the JCL to 
execute the program. Note that the 
IBM-supplied COPY members are used in the 
program. 



A typical applica 
character reader is 
premiums. Figure 19 
premium notice for t 
Insurance Company, 
lines of data to be 
contains one field, 
holder. The second 
fields: the second 
policyholder »s addre 
the premium amount d 



tion for an optical 
processing insurance 
5 shows an insurance 
he Standard Acme Life 
The document has three 
read. The first line 
the name of the policy 
line contains four 
line of the 
ss, the policy number, 
ue, and a code to be 



hand printed if the amount paid is 
different from the amount due. The third 
line contains one field that contains the 
amount paid if different from the amount 
due. 



Format Record Assembly Exa mple 



To process documents like that in Figure 
195, one format record is used. The format 
record must be created in a separate 
assembly. The coding necessary to create 
the format record is shown in Figure 196. 
The numbers at the left of the coding form 
correspond to those in text. Figure 197 
shows the data, from the document shown in 
Figure 195, as it is received by the 
program. 
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1. The job control language <JCL) 

statements indicate that the job is an 
assembly. The output from the 
assembly is linkage-edited into 
SYS1.IHAGELIB with a member name of 
FRLGIPN. The format record is 
identified by IPN. 



2. The DFR macro instruction specified 
the characteristics common to all 
lines on the document. The following 
information is provided: 

FON T?AN A1: The alpha aerie OCR- A font 
is used for reading any fields that do 
not have another font specified in the 
DLINT macro instruction field entries. 

REJECT= $: The commercial at sign {$) 
is substituted for any reject 
characters encountered. 

EDCHAR= {* ,« ,. ) : The comma and period 
are removed from one or more fields as 
indicated in DLIHT entries {line 2, 
field 3). 

3. The DLINT macro instruction describes 
one line type in a format record 
described by the DFR macro 
instruction. The following 
information is provided about the 
first line: 

LFR=1.LINBSG=4: The first line on the 
document has a line format record 
number of 1. The first field to read 
from the line begins four tenths of an 
inch from the left edge of the 
document. The data record is in the 
standard mode; editing is performed on 
both fields on the line. 



FLDl=f30,20.NCRITl r# .EDIT 1 = HLBL0F: The 
first field on the line ends 3.0 inches 
from the left edge of the document, the 
edited data is placed in a 20 byte 
field; the field is not considered 
critical. All leading and trailing 
blanks are removed, the data is left 
justified, and the field is padded to 
the right with blanks. 

FLD2= f42.5. NOMA) .EDIT2=ALBNQF: The 
second field ends 4.2 inches from the 
left edge of the document, the edited 
data is placed in an eight-byte field, 
the field is critical. All leading and 
trailing blanks are removed from the 
field. The resulting field must be 
eight digits in length or a wrong length 
field indicator is set. 

IIJ>3=l5.4 x 6 x J0HA) . EDIT3=HLBHIF.EDCHAR: 
The third field ends 5.4 inches from the 
left edge of the document, the edited 
data is placed in six-byte field, the 
field is critical. All leading and 
trailing blanks are removed, the data is 
right- justified, and the field is padded 
to the left with zeros. A comma, if 
present, and the decimal point are 
removed from the edited field. 

FLD4=f62,1, NHP1) iff ,EDIT4=ALEHIF: The 
fourth field ends 6.2 inches from the 
left edge of the document, the edited 
data is placed in a one-byte field, the 
field is critical and is read using the 
numeric handprinting normal mode. All 
blanks are removed, the data is 
right- justified, and the field is padded 
to the left with zeros. 

The third line on the document, is 
described as follows: 



FLpl=f32 J 20«NCRIT) , EDIT1=HLBLQF: The 
first and only field on the line ends 
3.2 inches from the left edge of the 
document, the edited data is placed in 
a 20-character field; the field is not 
considered critical. All leading and 
trailing blanks are removed, the data 
is left- justified, and the field is 
padded to the right with blanks. 

The second line on the document is 
described as follows: 

LFR=2 < ,LINBEG=4: The second line on the 
document has a line format record number 
of 2. The first field read begins four 
tenths of an inch from the left edge of 
the document. The data record is in 
standard mode; editing is performed on 
all fields on the line. 



LFR=3.L INBEG=45 : The third line on the 
document has a line format record number 
of 3. The field to read begins 4.5 
inches from the left edge of the 
document. The data record is in 
standard mode; editing is performed. 

FLDI^S^^NHPP ff EDIT1 = ALBHIF: The 
field on this line ends 6.3 inches from 
the left edge of the document, the 
edited data is placed in a seven-byte 
field, the field is critical, and is 
read using the numeric handprinting 
normal mode. All blanks are removed, 
the data is right- justified, and the 
field is padded to the left with zeros. 

FRElfD=XES: This is the format record 
end. No DLINT macros follow this 
statement. 
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STANDARDACME LIFE 

INSURANCE COMPANY 



NOTICE OF PAYMENT DUE 





DUE DATE 
MO DAY YR 


ANNIV 
MONTH 


DIST 
NO 


PREMIUM 






Ob 07 72 


0T 


H7A 


2ifl.75 





^ 



DALE E- STUEMKE 



13b3 SE 10TH AVE. 



ROCHESTER! MINNESOTA 



ab c mo3fit J 



EW.7S 



POLICY NUMBER 



$ AMOUNT DUE 



INSURED DAUN STUEMKE 

II yout address is other thin shown, please notily the 
Company. Please make check or money order payable to 
Standardacme Lite and present with notice to your 
Company Representative or to 



PLEASE RETURN WITH YOUR PAYMENT 



FOR COMPANY USE ONI': 



Figure 195. Sasple Document 
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YB|y| IBM Syiltm 360 Anunblor Coding Form «»■»" 


. P.OG..M , UNCM|NG C .»H,C 


TOW*! |oA<> """"^ '""« °"""°~" 




htomt Op.ra'.«> Optra*.! Comm.-... Wqunrx. 


1 77 JOBCARD * 


1 7/STEP EXEC PR0C=ASMFCL 


| Z2 ASN.SYSIM DD g T J 


I IHSPRM C5ECT 




x r ij 


X THIS ASSEMBLY MILL CREATE A FORMAT RECORD DESCRIBING AN * 


% INSURANCE PREMIUM NOTICE. V )i 


* " -"-- - - " --- { -- * 


, \ mmtfmimmim^^ 


{ DFR FONTTsANAl.REJECTsI.EDctiAR^C' ,' » .) 


1 DLlHT LFR*l.L'INBEO«4^ X 


FLP1»(32.20,NCRXT). X 


EPXTlcHLILOP 


DLIHT LFR=2,LlHBEft*4 X 


FLPi = t30 v 20 4 .HCRltl^ X 


EDIT1-HL3L0F X 


FLD2«T42 I ,8 ) _NUMA1 4 . X 


T EDIT2-ALBN0F. X 


FLD3-C54 4 .6^.NUMA1 + X 


edit3=hlbhif\edcmar\ I X 


FLD4»C62 v l,.NHPi) x X 


EDIT4-ALBHIF 


DLINT LFR»3. LINBE6»45, X 


'. FLDW*3.7 4 .NHPLL X 


■ 



IBM 



IBM Sy*ttm/360 AsMmbltr Coding Form 



„0«»M 






\Tu^ 


«».HK 






*C. 


nowwi 


U 




tU MC« 






CAIOfUrilONUMKI 


SUTIMtNl 




Id*nf.f't0t.<» 


, 


. ,0 '"""'"' ,. , t „ °",r 30 J5 « « 50 » C """" 60 


7, 73 


"*■"' 




EDI 


:ti*aubhif a 














- ^ -n 






_l FRl 


:ND=YE5 


















END 





















?*" 


















7Zlk 


ed.syslmod p_i 


> D5NAME*S 


YBl.IMAt 


iELIBCi 


-RL&l 


LPN^PISD' 


•OLP 








Z*_ 
















..... .... 







Figure 196. Format Record Assembly Coding Example 
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Line 1 


—^———— _______________-______^^^___-__^^___^___,^___. 


Header Record: 


01011 000000000000000 


(20 Bytes) 
Data Record: 


DALEbE.bSTUEMKEbbbbbb . . . b 


(130 Bytes) 


Policyholder Pad to 




Field 130 Bytes 


Line 2 




Header Record: 


0202 1 000000000000000 


(20 Bytes) 
Data Record: 


ROCHESTER,bMINNESOTA269403860249750b . . .b 


(130 Bytes) 


Address Policy Am ountS Pad to 130 Bytes 




Field Number Due 




Code 


Line 3 




Header Record: 


03031 000000000000000 


(20 Bytes) 
Data Record: 


0000000b . . . b 


(130 Bytes) 


Amount Pad to 




Paid 130 Bytes 



'igure 197. Sample Data 

Figure 198 shows the COBOL source stateaents used to process the data in Figure 197. 
'he JCL to run the prograa is also included in Figure 19 8. 
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' i 1— — ' " • - ■ -" ■ " 1 

*********************************** ************ **************************************** 
********* SAMPLE OCR PROGRAM ********* 

*************************************************************************************** 

ID DIVISION. 

PROGRAM-ID. DOCLIST. 
ENVIRONHENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT PRINTER. ASSIGN TO SYS009-UR- 1403-S. 
DATA DIVISION. 
PILE SECTION. 

FD PRINTER LABEL RECORDS ARE OMITTED. 
01 PRINT-RECORD. 

05 FILLER PIC X. 

05 PRINT-LINE PIC X(130). 

WORKING-STORAGE SECTION. 

77 PRINT-CONTROL PIC 9 VALUE 1. 

77 MSG-PERHANENT-ERROR PIC X(24) VALUE 

• PERMANENT ERROR OCCURRED*. 
77 MSG-M ARK-CHECK PIC X(19) VALUE 

'MARK CHECK OCCURRED'. 
77 NSG-MARK-AND-EQUIP-CHECK PIC X(39) VALUE 

•MARK CHECK AND EQUIPMENT CHECK OCCURRED'. 
77 MSG-INCGMPLETE-SCAN PIC X (24) VALUE 

'INCOMPLETE SCAN OCCURRED'. 
77 MSG-NONRECOVERY-ERROR PIC X(26) VALUE 

•NONRECOVERY ERROR OCCURRED'. 
77 MSG-BAD-DATA PIC X(50> VALUE 

•THE FOLLOWING LINE WAS MISREAD. THE LINE HEADER =*. 
01 MSG-TERHINATION. 

05 FILLER PIC X (44) VALUE 

•TERMINAL ERROR OCCURRED - OCR-STATUS-KEY = «. 
05 MSG-TERM-STATUS-KEY PIC XX. 

Figure 198. Saaple COBOL OCR Processing Program (Part 1 of 3) 



558 



01 OCR-FILE COPY IIBDOCRD. 

05 NOTICE-OF-PAYMENT-DUE REDEFINES OCR-DATA-RECORD. 
10 LINE-1. 

15 L1-POLICYHOLDER-RAME PIC X(20). 

10 LINE- 2 REDEFINES LINE-1. 

15 L2-CITY-AND-STATE PIC 1(20). 

15 L2-POLICY-NUHBER PIC X(8). 

15 L2-AMOUNT-DUE PIC 9<4)V99. 

15 L2-PAYMENT-VERIFY-CODE PIC 9. 

10 LINE-3 fiEDEFINES LINE-1. 

15 L3- A MOUNT- PAID PIC 9(5) V99.- 

PROCEDURE DIVISION. 

STOP RON. 
PIO-START. 

HOVE »SYS010« TO OCR-FILE-ID. 
HOVE •FORMAT 1 TO OCR-FORMAT-RECORD-ID. 
PERFORM OCR-OPEN. 
OPEN OUTPUT PRINTER. 
PIO-HEAD. 

HOVE ALL •*• TO PRINT-LINE. 
PERFORM PRINT-ROUTINE. 
MOVE 1 TO OCR-STACKER. 
PIO-READ. 

PERFORM OCR-READ. 

IF OCRS-NONRECQVERY-ERROR, GO TO PIO-EOP-ERR. 

IF ORCH-LINE-GOOD, GO TO PIO-GOOD. 

IF OCRH-LINE- BLANK, GO TO PIO-SOOD. 

IF OCRH-LINE-NON-CRITICAL-ERR, GO TO PIO-GOOD. 

IF ORCH-END-OF-PAGE, GO TO PIO-EOP. 

****IF ORCH HAS ANY OTHER CODE, CONSIDER THE DATA AS BAD **** 
PIO-BAD. 

MOVE MSG-BAD-DATA TO PRINT-LINE. 
PERFORM PRINT-ROUTINE. 
MOVE 2 TO OCR-STACKER. 
PIO-GOOD. 

MOVE OCR-DATA-RECORD TO PRINT-LINE. 
PERFORM PRINT-ROUTINE. 
MOVE 1 TO PRINT-CONTROL. 

ADD 1 TO OCR-LINE-NUMBER, OCR-LINE- FORM AT. 
IF ORCH-LINE- NUMBER IS LESS THAN 3, GO TO PIO-READ. 
PIO-EOP. 

MOVE 3 TO OCR-LINE- NUMBER. 
PERFORM OCR-EJECT. 
PIO-EOP-ERR. 

MOVE 1 TO OCR-LINE-NUMBER, OCR-LINE-FORMAT. 
MOVE 3 TO PRINT-CONTROL. 
GO TO PIO-HEAD. 
I : _,- .. 

Figure 198. Sample COBOL OCR Processing Program (Part 2 of 3) 
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****** EXCEPTION PROCESSING ROUTINE ************** 
QCR-EXCEPTION-ROUTINE. 

IF OCRS-END- OF- FILE, GO TO P20-EOF. 
IF OCRS -MASK- CHECK, 

MOVE MSG-MAHK-CHECK TO PRINT-LINE, 

GO TO P20-RETURN. 
IF OCRS-NONRECOVERY-ERROR, 

MOVE MSG-NGNRECOVERY-ERROR TO PRINT-LINE, 

GO TO P20-RETURN. 
IF OCRS-INCOMPLETE-SCAN, 

MOVE MSG-INCOHPLETE-SCAN TO PRINT-LINE, 

GO TO P20-RETDRN. 

IF OCRS-MARK-AND-EQUIPMENT-CHECK, 

MOVE MSG-MARK-AND-EQUIP-CHECK TO OCR-LINE, 
GO TO P20-PRINT-EOF. 

IF OC8S-PERMANENT-ER80R, 

MOVE MSG-PERMANENT-ERROR TO PRINT-LINE, 
GO TO P20-PRINT-EOF- 
****** IF N0NE 0F THE ftBOVE ERRORS, GIVE TERMINATION MESSAGE ****** 

MOVE OCR- ST AT US -KEY TO NSG-TERM-STATUS-KEY. 

MOVE MSG-TERMINATION TO PRINT-LINE. 

GO TO P20-PRINT-EOF. 
P20-RETURN. 

PERFORM PRINT-ROUTINE. 

GO TO OCR-CALL-EXIT. 
P20-PRINT-EOF. 

PERFORM PRINT-ROUTINE. 
P20-EOF. 

PERFORM OCR-CLOSE. 

CLOSE PRINTER. 

STOP RUN. 
PRINT-ROUTINE. 

WRITE PRINT-RECORD AFTER ADVANCING PRINT-CONTROL. 
OCR-COPIED-PROCEDURES. COPY ILBDOCRP. 
/* 

//LKED. SYSIN DD* 
ENTRY DOC LI ST 

/* 

//GO.SYSPRINT DD SYSOUT=A 
//GO.SYSUDUMP DD SYSOUT=A 
//GO.SYS010 DD DUMMY 



Figure 198. Sample COBOL OCR Processing Program (Part 3 of 3) 



PfiOCESSING TAPES FROM THE 3886 OCR, MODEL 2 



Tape records produced fro a the IBM 3886, 
Model 2, are almost identical in format to 
the header and data records returned by the 
Model 1. The main differences between the 
records are: 



Because of the similarity, however, the 
Data Division COPY member defined for the 
Model 1 may be tailored to describe the 
Model 2 tape records. To do so, the 
programmer should punch out the COPY 
member, modify it according to the 
installation requirements, and recatalog 
it. 



1. The Model 2 tape contains a document 
trailer record after the line output 
records for each document. The 
content of this trailer record differs 
from that of line output records. 

2. The codes used in certain fields of 
the header record differ between the 
two models. 



Specific information on the formats and 
contents of the Model 2 tape records is 
contained in the IBM 3886 O ptical Cha r ac ter 
Reader. General Information Manual 
(GA21-9146). 
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INDEX 



As an aid to readers, this index contains not only the conventional references to 
material in this Programmer ' s Guide , but also references to material that can be found 
in the COBOL language manual. Entries having page numbers refer to pages in this manual, 
Entries having only asterisks point to IBM VS COBOL for OS/VS (GC26-3857) . For example: 

Able 347 
Baker* 

Charlie 89, * 
Dog 23, 106 
Easy 

additional information* 

sub-one 33 

sub-two 400 

These entries would indicate that information on the subject "Able" is available on page 
347 of this manual, and information on "Dog" is available in this manual on pages 23 
and 106. Information on "Baker" does not exist in this manual; it can nevertheless be 
found in the language manual (by looking up "Baker" in that manual's index). The entry 
for "Charlie" indicates that some information is available in this Programmer's Guide 
(on page 89), and additional information can be found in the language manual (again, by 
looking up "Charlie" in its index) . The entries for "Easy" indicate that its "sub-one" 
and "sub-two" aspects can be found in this manual (on pages 33 and 400, respectively); 
additional information on "Easy" is also available in the language manual. 



. (period)* 

< (less than character) * 

() (parentheses) * 

♦ (see plus symbol) 
$ (currency sign) * 

* (see asterisk) 

** (exponentiation) * 

; (semicolon)* 

- (see either hyphen, or minus symbol) 

/ (slash) 48,* 

, (comma) * 

> (greater than character)* 

= (egual sign) * 

' (apostrophe, single guote) * 

" (quotation mark)* 

6&name subparameter 58 

*. ddname subparameter 57 

*. procstep subparameter 57 

*. stepname subparameter 57 

/* delimiter statement 21, 70 

//* comment statement 23 



A, as a device class 21 

A, used in PICTURE and CURRENCY SIGN clauses* 

abbreviations 

for compiler options 38 

for source statements* 
ABDUMP (see dumps) 
ABEND (see abnormal termination) 
ABEND request subroutine 254, 481 
abnormal termination 

avoided by 



FILE STATUS 293 

ON OVERFLOW 295 
causes 254-259 

completion codes 257-259, 529 
COND parameter 35-37 
dump 

causes 254-259, 529 

DD statement required for 81 

definition 254 

example 262-268 

finding records in 268-273 

how to use 260-262 

including problem program storage 
area 69 

including system nucleus 69 

of data sets 69 

requesting 80-81, 254 

required DD statement 81 

using 254 
errors causing 254-259 
EVEN subparameter 37-38 
failure to occur 183 
for COBOL files 143-154 
incomplete 277 

INVALID KEY clause 148, 153-154 
ONLY subparameter 

restarting a job 36 

restarting a job step 47 

resubmitting a job 36 

USE AFTER ERROR declarative 148-154 
sort/merge considerations* 
U-type codes 529 
absolute LINE and NEXT GROUP* 
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(VSAM) 



173-180, 186, 



85-88 



ABSTR subparameter 
description 61 
in QISAM 124 
ACCEPT statement 

additional information* 
relationship to SYSIN DD statement 80 
subroutine for 477 
ACCESS IS phrases* 
access method services 
access methods for 
direct file 

randomly 97-98 
sequentially 98 
indexed file 

randomly 129-131 
sequentially 127-129 
queue structures 312 
relative file 

randomly 112-113 
sequentially 111-112 
standard sequential file 
ACCESS MODE clause* 
accountinq information 
EXEC statement 34, 20 
JOB statement 26, 20 
accuracy of results 294, * 
action requests, status key settinqs 

(VSAM) 190*193 
actual decimal point * 
actual key 83, 92-94 

(see also ACTUAL KEY clause) 
ACTUAL KEY clause 

(see also actual key) 
in BDAM 92-94, 83- 
in BSAM 92-94, 83 
in file processinq techniques 
randomizing techniques 

division/remainder method 
relative addressing 101 
synonym overflow 108 
ADCON table (see Text Punch Table) 
ADD statement * 
addition operator* 

address constant table (see Text Punch Table) 
ADDRSPC parameter 

and REGION parameter 
description 31, 51 
ADV compiler option 44 
ADVANCING 297, * 
AFF parameter 58, 59 
AIXBLD option 186, 48, 



492, 493 
102 



31, 51 



201 



66 



69 



AL subparameter 

alqebraic siqn* 

ALIGN subparameter 

aliqnment rules* 

ALL literal fiqurative constant* 

ALL options* 

allocatinq mass storaqe space 
SPACE parameter 61 
SPLIT parameter 62 
SUBALLOC parameter 16 4 

allocation messages 235, 241, 243 

alphabet-name* 

alphabetic characters* 

alphabetic class test* 

alphabetic item* 

alphanumeric class* 

alphanumeric edited item* 



alphanumeric item* 

ALSO option* 

ALTER statement* 

altered GO TO* 

alternate collatinq sequence subroutine 48 

(see also collatinq sequence) 
alternate indexes (VSAM KSDS) 

ddnames for 201 
"*> defininq 177 

described 173, 174 

examples 182, 195, 197 

processinq 181, 190 

writinq 189 
alternate keys (see alternate indexes) 
alternate paths 174 
alternate record key* 

(see also alternate indexes) 
ALTERNATE reserved word* 
ALTERNATEINDEX command 175, 178 
ALX subparameter 61 
American National standard (see ANS 

standard) 
American National Standard Code for 
Information Interchanqe (see ASCII) 
AMP parameter 201, 69, 56 
AND loqical connective* 
\NS standard 

additional information* 

requirements for MCP 432 

selectinq 38 
APOST compiler option 40 
APPLY clause 

CORE-INDEX option 283 

RECORD-OVERFLOW option 283 

WRITE-ONLY option 282 
arabic numerial* 
Area A and Area B* 
arquments 

data-name passed as 317, 322 

file-name passed as 317, 322 

procedure-name passed as 317, 322 
arithmetic expression* 
arithmetic operator* 
arithmetic statements* 
arithmetic subroutines 475-476 
ASCENDING/DESCENDING Key* 
ASCII 

additional information* 

block prefix 90 

collating sequence 293 

creating 89 

description 89-90 

label processing 90, 158-159 

numeric data items 90 

opened 90 

processing 90 

reguesting for QSAM 90 

sort for 375 
assembler language 

programs, linkage to 322-325 

usinq EXEC statement 32-37 
ASSIGN clause 

additional information* 

for ASCII file 89-90 

in BDAM 82 

in BSAM 82 

in QSAM 85 

relationship to DD statement 82-83 
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assigning index values 306-307, * 

assignment name 82, 100, * 

assumed decimal point* 

assumed values in PAGE clause* 

asterisk 56, * 

AT END 56, * 

ATTACH macro to invoke compiler 499 

AUL subparameter 66 

automatic call library 349 

automatic restart (see Checkpoint/Restart) 

automatic page overflow* 

automatic volume recognition option 

(AVE) 58 
automatic volume switching 99 
availability of records* 
average record-length subparameter 
for SPACE 61 
for SPLIT 62 
AVR (automatic volume recognition 

option) 58 
AWAITING REPLY* 



B, as a device class 21 

B, used in PICTURE and CURRENCY SIGN 

clauses* 
bacHc-v^r-dr-EKyveiBeiit (optimization) 279 
base and displacement 246 
BASIS card 

additional information* 

and batch compilation 71-73 

in a debug packet 254 

use of 351-352 

BASIS library 76 

batch compilation 71-73 

BATCH compiler option 42 

BDAM 

data sets 134 

DD statement parameters 109 

defining a data set in 82-83 

definition 83 

direct organization 91 

error processing for 143-154, 509 

locating data areas in 275 

relative organization 110-112 

permissible COBOL clauses 118, 108 

programming techniques 283 

with spanned records 261 
BEFORE ADVANCING* 

BEFORE/AFTER option of INSPECT* 
beginning address of a file 62 
binary (see also computational fields)* 
BISAM 

(see also QISAM, indexed files) 

considerations when using 129-131, 119 

data sets 134 

defining a data set in 82-83 

definition 83 

error processing for 143-154, 509 

processing with 129-131, 119 
blank line* 

BLANK WHEN ZERO clause* 
blanks 

additional information* 

in job control notation 25 
BLDINDEX command 174, 186 



BLKSIZE 

for compiler data sets 496-498 

in DCB 491-495 

in file processing techniques 87 

in QSAM 125 

with data sets 79-80 
BLOCK CONTAINS clause 

additional information* 

and UNIT subparameter 59 

description 59 
block length (see BLKSIZE) 
block prefix 90 
block size 

causing errors 256 

description 59 

for utility data sets 496-498 
blocked records 

fixed-length 160 

spanned 164-166 

variable length 161-164 
blocking, automatic* 
BLP subparameter 66 
body group* 
bottom page margin* 
boundary alignment* 
boundary violation* 
braces in job control notation 25 
ibrackets in job control notation 25 
BSAM 

data sets 133 

DD statement parameters 109 

defining a data set in 82-83 

definition 83 

error processing for 143-154, 509 

locating data areas in 275 

permissible COBOL clauses 108, 118 

subroutines 478 

user label totaling 156 

with direct file 91 

with relative file 110-112 

with spanned records 261 
BUF compiler option 38 
buffer offset 89 
buffer unit 426 
buffers 

additional information* 

for TCAM 426 

optimizing with APPLY clause 164 

size of compiler's 497 

specifying number 

for indexed files 124 
for standard sequential files 87 
BUFNO subparameter 124 
BUFOFF subparameter 90 
byte, definition* 



as compiler message level 238, 35 

as COPY indicator 235 

as FIPS level 40 

in source* 
CALL loader option 48 
CALL macro 323, 326 
CALL statement 

additional information* 

and CANCEL statement 295, 323-326 

and subprograms 295 

definition 295 
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dynamic loading 335-336 
samples 327-331 
calling/called programs and subprograms 
additional information* 
additional input 332, 346 
identifiers 322 
input 

additional 332, 346 
primary 332, 346 
linkage 316-326 
loading 346 
primary input 332, 346 
sample 327-331 
CANCEL statement 

additional information* 

and static CALL statement 295 

and subprograms 323-326 

description 295 

format 295 
capacity records 93 
card files* 
card image* 

carriage control character 44, * 
catalog, system 18 
cataloged data sets 

creating 136 

description 141 

on a volume 155 

retrieving 138 
cataloged procedures 

adding to the procedure library 357-35* 

adding to DD statements 364 

bypassing steps within 35-37 

calling 356 

COBUC 359, 360 

COBUCG 361, 360 

COBUCL 359, 360 

COBUCLG 361, 360 

COBDLG 359-360 

data sets produced by 356-357 

DD statements 51 

ddname parameter 366-367 

definition 21 

dispatching priority 50 

IBM-supplied 358-359 

in-stream testing 363 

limiting execution time of 51 

modifying 362 

naming 359 

overriding 362 

PEND statement 70 

PROC statement 70 

programmer-written 357 

required device class names for 58, 59 

restarting programs with 28-29 

return code 34-36 

using the DD statement 364-368 

using the EXEC statement 34, 362 

with COND parameter 35-37 
categories* 
CATLG subparameter 67, 141 



CBL card 

and batch compilation 71-73, 42-43 

and lister options 44 
CD entries 284, * 
cd-name* 

CDECK option of lister 44, 212 
CF* 
CH* 

changing values* 
channel, definition* 
character codes* 
character delimiters 24 
character positions* 
character set 

additional information* 

UCS parameter 60 
character- string* 
characters allowed* 
CHARACTERS option* 
checkid 29, 396-397 
checklist for job control 

procedures 514-518 
Checkpoint 

(see also Checkpoint/Restart) 

additional information* 

CHKPT macro instruction 28-29, 396 

considerations 396-397 

data set 28-29 

how taken 49-50 

initiating 394 

in a job 28-29 

in a job step 49-50 

messages 3 96 

multiple 394 

RERUN clause 49-50, 394 

restart 49, 397-398 
(see also Restart) 

single 394 
Checkpoint/Restart 

checkpoint 394-396 

(see also checkpoint) 

data sets 398-400 

DD statements 394-396 

deferred 69 

designing 396 

in a job 28-29 

in a job step 49 

messages 396 

methods 394 

RD parameter 

with checkpoint 396-397 

for a job 28 

in a job step 49 

restart 397-398 

(see also Restart) 

subroutine 478 

SYSCHK DD statement 397-400, 69 

with Sort/Merge 372 
CHKPT macro instruction 28-29, 49 
CJS (see Communications Job Scheduler) 
class condition* 
CLASS parameter 30 
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class test subroutine 476 

classes of data* 

clause sequence* 

CLIST compiler option 39 

CLOSE REEL statement 85 

CLOSE statement 

additional information* 

BSAM subroutines 478 

creating multivolume files 

with direct organization 98 
with relative organization 112 

efficient use 295 

VSAM files 191 
CLOSE UNIT statement 98, 112 
closed subroutine* 

cluster considerations (VSAM) 180 
CMS (Conversational Monitor System) 

operating system 19 

VM/370 19 
COBOL copy libraries 73, 76 

COBOL sequence numbers 351 

entering source statements 349 

IEBOPDTE sequence numbers 351 

retrieving source statements 351 
BASIS card 351, 35 
COPY statement 35, 351 

updating source statements 350 
COBOL file processing (see file, processing 

techniques) 
COBOL Interactive Debug (see Interactive 

Debug) 
COBOL language usage with VSAM 193-201 
COBOL library management* 
COBOL library subroutines 472-489, 348 

(see also library) 

concatenating 353 

sharing 353 
COBOL program structure* 
COBOL RERUN clause 49-50, 394 
COBOL reserved word list* 
COBOL sample program 461-471 
COBOL sequence numbers 351, 39 
COBOL subroutine library 348, 472 

(see also library) 

need to concatenate 81 
COBOL subroutines in link pack area 346 
COBOPIN 432 
COBOPOOT 432 
COBOPT 433-434 
COBTPOUT 449 
COBTPQD 449 
COBOC 359, 360 
COBUCG 361 
COBOCL 359, 360 
COBOCLG 361 
COBULG 351, 360 
COBORDR procedure 437 
CODE clause* 

CODE-SET phrase 90, 293, * 
codes, completion 257-259 

for Sort/Merge program 371 
collating sequence 

additional information* 

and ACTUAL KEY 94 

effect on QISAM 129 

for QSAM 90 

for Sort/Merge 375 

general 293 



COLUMN clause* 

combined condition and function* 

combining arithmetic operations* 

comma* 

command statement 70 

comment- entry* 

comment line* 

comment statement 71 

comments 

continuing 24 

field 24 

statement 71, 20 
common end point* 

common expression elimination 279 
Communication Description (CD) entries 

additional information* 

and Communications Section 284 

and Teleprocessing (TP) 284 

format 284 
Communication Feature (see also 
Communications Job Scheduler) * 
Communication Section 284, * 
communication with other languages 326 
Communications Job Scheduler 

general 436 

illustrations 439-441 

preparing 438 

using 438 
compare subroutine 476 
comparison rules* 
compatibility (LANGLVL) 38 
compilation 

(see also compiler) 

additional information* 

batch 71-73 

cataloged procedure 356-360 

checklist for job control 
procedures 514 

data set requirements 73-76 

definition of 18 

example of job control 
statements 514 

invoking compiler at execution 
time 499-500 

sample program 461-471 

source program size assuming minimum 
configuration 501 

syntax checking 247 

using REGION parameter 457 

COMPILE= indicator 237 
compiler 

(see also compilation) 

additional information* 

blocking factor for data sets 496 

buffer space 497 

calling 499 

capacity 501 

data set reguirements 73-76 
block size 496 

internal name 236 

invoking 499 

machine requirements 457 

optimization 496-498 

options 38-46 

significant characters 38 

output 

allocation messages 235 
cross-reference dictionary 237-238 
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diagnostic messages 238 
global table 236-237 
glossary 235-236 
job control statements 235 
object code 237 
object module 239-240 
sample output 232-236 
source module 235 
PARM options 38-46 
problems, resolving 543 
return code 500 
segmentation output 379 
specifying in EXEC statement 32 
compiler-directing statement* 
completion codes 

description 257-259, 529 
in Sort program 371 
complex conditions* 
composite of operands* 
compound condition* 
computational fields 

conversion subroutines 473-475 
conversions involving 288-290 
description 288 
COMPUTATIONAL* 
COMPUTE statement* 
computer- name* 
concatenating 
data items* 
libraries 69 
COND parameter 

EVEN, ONLY subparameter 36 

in cataloged procedures 372-373 

in EXEC statement 3 5-37 

in JOB statement 27 
condensed listing, used to find program 

interruption 259 
condensed listing, using CLIST 38 
condition* 
condition- code* 
condition-name* 
conditional, as a severity level 

(C) 38, 35 
conditional expressions and statements* 
conditional syntax-checking compilation 41 
conditional variable* 

conditions terminating execution 27, 35-37 
conditions valid in serial search* 
Configuration Section 282-283, * 
connective words* 
console message* 
CONSOLE typewriter* 
CONTIG subparameter 

description 61 

with direct files 100 

with indexed files 124 
contiguous items* 
continuation 

additional information* 

of job control statements 24 
control breaks* 

(see also CONTROL clause) 
control cards 

for CJS 438 

for SYMDMP 215-216 
control characters 436, * 



CONTROL clause* 

control flow* 

CONTROL FOOTING* 

CONTROL HEADING* 
control hierarchy* 
control program 18 
control statements 

character delimiters 24 

command statement 70, 20 

comment statement 71, 20 

continuing 24 

DD statement 51-70 

delimiter statement 70, 20 

EXEC statement 32-51, 20 

fields 23-24 

formats 23 

functions 22 

JOB statement 25-32, 20 

notation used for 25 

null statement 70, 20 

PEND statement 70 

preparing 23-24 

PROC statement 70, 20 

processing 22 

use 20 
control transfer (see also calling 

programs and called programs)* 
Conversational Monitor System (see CMS) 
conversion of data 473, * 
conversion subroutines 473-475 
COPIES parameter 60 

copy library (see COBOL copy library) 
COPY statement 

additional information* 

DD statement reguirements 515 

effect of CDECK option 44 

use 349-351, 35 
core fragmentation, preventing 43 
core storage (see main storage) 
core storage availability to sort* 
CORRESPONDING option* 
COUNT compiler option 44 

DD statement 81 

program checkout 247, 278 

count field in INSPECT* 

COUNT IN, UNSTRING* 
COUNT subroutines 482 
counter rolling* 
counting characters* 
CR, used in a PICTURE clause* 
creating files, DD statement 
considerations 131-137 

direct 134 

in the output stream 134 

indexed 134 

on magnetic tape 133 

relative 111-112 

seguential, on mass storage device 133 
credit (CR) * 

unit record 133 
cross- footing* 
cross-reference 

dictionary 237-238 

list 

description 242 

of verbs (VBREF) 44 

used in dumps 262-263 
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CRP (current record pointer) 181 

CSP-f unction-name* 

CSYNTAX compiler option 41 

CURRENCY-SIGN clause* 

CURRENT-DATE special register 481, * 

current record pointer (CRP) 181 r * 

CYL subparameter 

for SPACE 

considerations for indexed files 124 
description 61 

for SPLIT 62 
cylinder overflow area 122-123 
C01 through C12 function name* 



as message level 35, 228, 529 

in source* 

indicating debugging lines 24 8 
data alignment 288-292 
data areas, locating in a TCAM 

program 275-277 
data attribute* 
data classes* 
data control block 

(see also DCB parameter) 

description 142 

fields 490-495 

identifying 143 

overriding fields 142-143 
data conversion 288-292, * 
data-count fields* 
data definition 51-69, 20 

(see also DD statement) 
data description* 
data delimiter for input 56 
Data Division additional information* 

maximum size 283 
Data Division dump (with SYHDMP) 

and FD 214 

and index-name 214 

and RD 214 

and SD 214 
Data Division programming techniques 283-292 
Data Division reformatting 204-2 05 
data extent block 73 
data formats 285-289 
data group, generation 141-142 
data hierarchies* 
data item* 

data manipulation statements* 
data-names* 

additional information* 

missing from listings 42, 238 
data-name clause* 
data organization* 
DATA parameter 

in DD statement 56 

restriction with UNIT parameter 59 
data receiving fields* 
DATA RECORDS clause* 
data reference* 
data representation* 
data set control block 155, 56-68 
data set labels 

description 154-159 

relationship to DD statement 154 



specification of 82 
data set member 83 
data sets 

adding records to 67 

(see also MOD subparameter) 
allocating space for 61-64 
blocked 79-80 
cataloging 

description 67 

indexed files 141 
checkpoint 398-400 
concatenating 364 
copies of 60 

creating 131-137, 174-180 
definition 18 
deletion of 67 

delimiting in input stream 70 
describing attributes of 51-56 
direct 83, 91-97 
disposition of, in general 131 

after abnormal termination 277-278 

description 67-68 
errors involving 255-259 
ESDS 173 

execution time 79-81 
extending 142 

for symbolic debugging 246, 215, 216 
for VSAM 201-202 
generation data groups 141-142 
identifying 

description 57 

for compilation or linkage 
editing 57 
in the input stream 56 
in the output stream 68-69 
indexed 119-131 
ISAM 202 
KSDS 173 
labels, relationship to SELECT and DD 

statements 144 
magnetic tape 133 
multivolume, processing 98 
names 

description 142 

relationship to file names 82 
nontemporary 63 
number of copies 60 
organization 83 
partitioned 347-355 
physical sequential 85-89 
postponing definition of 57 
produced by cataloged 

procedures 356-357 
relative 83 
retaining 67 
requirements 

for compilation 73-76 

for execution 79-81 

for linkage editing 76-78 

for loading 78-79 
retrieving 138-140, 195< 

(see also retrieving data sets) 
RRDS 174 

scratching 277-278 
sharing 67 

standard (physical) sequential 85-89 
system catalog of 18 
temporary 63 
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unit record 133 
updating (VSAM) 198-199 
used by Checkpoint/Restart 380-382 
used by Sort 349-351 
VSAM 173-202 
data transfer* 
data truncation* 
data values REDEFINES* 
Date-and-Time subroutine 481 
DATE-COMPILED paragraph 235, * 
DATE special register 481, * 
DATE-WRITTEN paragraph* 
DAY special register 481, * 
DB, used in a PICTURE clause* 
DCB exit subroutine 479 
DCB macro instruction 490 
DCB parameter 58 

(see also data control block) 
for defining checkpoint data 

sets 398-400 
description 143 
error processing with 143-146 
identifying information' in 143 
retrieving previously created data 

sets 138-140 
subparameters 

for direct files 

accessed randomly 493 
accessed sequentially 4 92 
for indexed files 

accessed randomly 139, 495 
accessed sequentially 128, 494 
for physical sequential files 86-89 
for relative files 

accessed randomly 493 
accessed sequentially 120, 492 
DD statement 51-69 

adding to a cataloged procedure, 

description 21 
additional information* 
error recovery option, for physical 

sequential files 143-146 
facilities, additional 69 
format 52-56 
name field 56 
overriding in cataloged 

procedures 364-365 
parameters 52-68 
AFF 58 
AMP 69 
asterisk 56 
COPIES 60 
DATA 56 
DCB 58 
DDNAME 57 
DISP 66-68 
DLM 56 
DSNAME 57 
DUMMY 56 
DYNAM 57 
FCB 68 
LABEL 62 
OUTLIM 60 
QNAME 58 
SEP 58 
SPACE 61 
SPLIT 62 
SUBALLOC 62 



SYSOUT 68 

TERM 60 

UCS 60 

UNIT 58-59 

VOLUME 63-66 
relationship to ACCEPT statement 80 
relationship to DISPLAY statement 79-80 
relationship to SELECT statement 144 
requirements for 

ASCII files 90, 159 

changing a library 357 

compilation, job step 514, 515 

compiler data sets 73-76 

creating files (see creating files, 
DD statement considerations) 

direct files 109 

execution job step 515, 516 

execution time data sets 141 

extending data sets 139 

indexed files 123-129, 510-513 

linkage editing 

data sets 76-78 
job step 515, 516 

loader data sets 78-79 

physical sequential files 85-89 

relative files 110, 138-140 

retrieving data sets 138-140 

sort/merge 368-371 

specifying unit record devices 141 

standard (physical) sequential 
files 85-89 

unit record devices 141 

using cataloged procedures 357-361 

using COBOL copy library 349-350 

using the sort/merge feature 368-371 

VSAM files 201 
sort/merge, used in 368-371 
subparameters 

DISP 67 

DSNAME 57 

FCB 68 

LABEL 66 

SPACE 61 

SPLIT 62 

SUBALLOC 62 

SYSOUT 68 

TERM 60 

UNIT 59 

UCS 60 

VOLUME 65 
used to complete the DCB 142-143 
user catalog (VSAM ( 201 
DDNAME parameter 57 

ddname subparameter (see ddname 

subparameter) 
description 57 
in cataloged procedures 366 
ddname subparameter 57 

and calling and called programs 34 
and cataloged procedures 364-365 
and creating files 133-134 
and indexed files 123-127 
and retrieving files 138-140 
and subprogram linkage 337-339 
and VSAM 201 
as DDNAME subparameter 57 

(see also DDNAME parameter) 
as DSNAME subparameter 57 
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as INCLUDE operand 338 

as LIBRARY operand 338 

as PGM subparameter 34 

as stepname qualifier 364-365 

as SUBALLOC parameter 62-63 

checklist of use in JCL 
procedures 515, 516 

in DD statement format 53 

in EXEC statement format 34 

in name field of DD statement 56 

used to allocate space 62-63 

using with queue structures 313 

with Checkpoint/Restart 394, 396 
DEBUG card 236, * 

debug control statement, sort/merge 377 
debug control subroutine 482 
DEBUG-CONTENTS field 249, * 
DEBUG-ITEM special register 248, * 
DEBUG fields in PGT 525 
DEBUG option 48, 248 
DEBUG- LINE* 
DEBUG- NAME* 
DEBUG-SUB* 

debug, interactive (see Interactive Debug) 
debugging features 213-230, 247-254, * 
debugging language 247-254 

(see also TRACE statement and EXHIBIT 
statement) 
debugging lines 248, * 
debugging packet 251, * 

debugging a program (see program debugging) 
debugging, symbolic 213-230 

example 217-230 

FLOW 214 

STATE 213 

SYMDMP 214-215 

TEST 213 

under IMS 217 
DECB, linking with 317 
decimal point 

additional information* 

alignment in PICTURE clause 286 
DECIMAL- POINT IS COMMA clause* 
DECK compiler option 39 
declarative save area chaining 

subroutine 4 80 
declaratives 

additional information* 

USE AFTER ERROR 143-154 

USE FOR DEBUGGING 248 
decrementing* 
defaults 

additional information* 

for data sets 498, 216 

for options 46 
DEFER subparameter 59 
deferred restart 397-398 

SYSCHK statement 69 
DEFINE command 

cluster considerations 177 

ESDS 179 

functions 174 

KSDS 177 

MASTERCATALOG 175 

RRDS 179 

specification of 174 

USERCATALOG 176 

VSAM data space 176 



DELETE statement 137, 352, * 

in VSAM 190 
DELETE subparameter 

and cataloged data sets 141 

definition 67 
deleting modules 43 
DELIMITED BY* 
delimiter 

additional information* 

in job control statement 24, 70 
DEN subparameter 86 
DEN values 86 
DEPENDING ON option 305, * 
depth of a report page* 
descending key* 
destination* 
DETAIL* 

detail reporting* 
determining file space 101 
device allocation 235 
device class 

and compiler data sets 73-76 

and execution time data sets 79 

and linkage editing data sets 76-78 

and UNIT parameter 59 

blocking restrictions 59 

definition 18 

examples of names 21 

names required for cataloged 
procedures 59 
diagnostic messages 

compilation 238-239, 529 

linkage editing 240-241 

object-time 529 

sort/merge 370 

with ON statement 214 
DIAGNS subparameter 88 
dictionary, cross-reference 237-238 
dictionary table 502 
digit position* 

direct access (see mass storage) 
direct data sets 

creating 94-97 

description 91-94 
direct file 

ACTUAL KEY clause 91 

creating 94-99 

randomly 96-97, 99 
sequentially 94-95 

description 91-94 

error processing 143 

multivolume 98 

processing 91-109 

randomizing technique 100 

readinq 

randomly 97 
sequentially 97 

sample program 106-107 

space allocation 94 

TRACK LIMIT clause 94 

writing 99-100 
direct indexing* 
Direct SYSOUT Writer 134 
directory-quantity JCL subparameter 62 
DISABLE statement 

additional information* 

qeneral 297, 432-434 

subroutine for 480 
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disaster, as a severity level (D) 35, 228, 
disk (see mass storage) 
DISP parameter 66-70 

data set uses 

cataloging 141 
creating 133-134 
retrieving 138-140 

default values of 67 

description 66 

in JOBLIB DD statement 67 

in sort/merge feature 369-370 

subparameters 67-68 
displacement* 

displacement and base 236 
DISPLAY option of USAGE clause 

additional information* 

and comparisons and moves 288, 290 

and data format conversion 289 

external decimal format 290-292 
DISPLAY statement 

additional information* 

and COBOL output files 79-80 

conversions involving 288-290 

relationship to DD statement 79-80 
DISPLAY subroutine 477 
DISPLAY usage* 
displaying data values during 

execution 251-253 
disposition messages from job 

scheduler 241, 239 
disposition of a file, in general 131 
DIVIDE statement* 
division header, description* 
division operator* 
division/remainder method for 

randomizing 102 
DMAP compiler option 39 
document description (OCE) 550 
document design (OCR) 549 
dollar sign* 
DPETY parameter 51 
DSNAME parameter 57 

and single-volume files 125-126 

and file creation 131 

and file processing technigues 
direct 109 
indexed 123 
relative 119 
standard seguential 88 

definition 57 

format of 53 

subparameters 57 
DSNAME subparameters 57 
DSORG 

direct files 109 

indexed files 128 

relative files 120 
dummy data set, defining 366 
DUMMY parameter 

definition 56 

format 53 

restriction 74 
dummy records 93, 186 
DUMP compiler option 44 
dumps 

and symbolic debugging 213 

completion codes 257-259, 529 

DD statements to reguest 81 



529 definition 69, 254 

determining location of error 259-260 
DUMP option 44 
dynamic 251-254 

and compile-time option 251 
SYHDMP 254 
locating records in 268-273 
locating working-storage in 237 
reguesting 

using ILBOABN0 subroutine 254-255 
using SYSABEND DD statement 81 
using SYSUDUMP DD statement 81 
types of 

abnormal termination 260, 254 
DUMP option 44 
indicative 254 
use of 254 
user-initiated 254 
duplicates, alternate keys 173, * 
duplicates, names* 
DYNAM option 334-336 
DYNAM parameter for TSO 57 
dynamic access* 
dynamic CALL 334-336, * 
dynamic dump, symbolic debugging 213 
dynamic invocation of Access Method 

Services 186 
dynamic subprogram linkage 317-321 
and static CALL statement 295 
CALL 318 

CANCEL statement 295 
DYNAM option 334-336 
example 319-321 
NODYNAM 336 
dynamic values in table* 



E (error severity level) 238, 35 
EBCDIC 

additional information* 

as program collating seguence 293 

as label format 155 

for M0DE= specification 87 
editing* 

efficiency guidelines (optimization) 281 
efficient programming (see programming 

techniques) 
EGI (end-of-group indicator)* 
elementary entries* 
elementary item* 
ellipsis (...) in formats 25 
ELSE NEXT* 
embedded PERFORM* 
EMI (end-of-message indicator) * 
ENABLE statement 

additional information* 

general 297, 432-434 

subroutine for 480 
END DECLARATIVES* 
end indicators* 
end key* 

end of execution 43, 323, * 
end-of-file 56,* 
end-of-group indicator (EGI)* 
end-of-message indicator (EMI)* 
end-of-page condition 297, * 
end- of -procedure* 
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end- of- program* 

END OF REEL* 

en d-of- segment* 

end of sort/merge* 

end of table* 

end of transmission* 

ENDJOB compiler option 43, 323 

ENTER statement* 

entry name 334, 317 

entry-point 

of called programs 334 

of loaded programs 48 
entry- seguenced VSAM data sets 173 
ENTRY statement 334, * 
Environment Division 

additional information* 

programming technigues 282-283 

reformatting 204 
EOP* 

EP loader option 48 
egual sign* 
egual size operands* 
EQUAL TO* 

EROPT subparameter 87, 146 
error 

additional information* 

as a severity level (E) 238, 35 

completion codes with 35, 257-259, 529 

conditions 

input/output 504-509 
invalid data 257-259 

escaping detection 294 

messages 

condition code 35, 529 
compile time 238-239, 529 
linkage editor 240, 242 
loader 243 
numbered 77 
object time 529-542 
system 246, 243 
severity codes 35, 238 
U-type 529 

processing for COBOL files 144-154 

recovery 142-154 
error intercept subroutines 478 
error processing, RECEIVE* 
error processing for COBOL files 

COBOL language features for 143 

error declarative 148-154 

EXCEPTION/ERROR procedure (VSAM) 183 

flow of logic and control 147 

GIVING option example 150-152 

INVALID KEY option 148, 183, 508-509 

VSAM 183-185 

outline of error recovery 143-146 

status key (VSAM) 183 

summary of error recovery 154 
error records* 

ESD (see external symbol dictionary) 
ESDS data sets (VSAM) 

defining 179 

general 173 

opening 189 

processing 180, 189, 196 

writing 193-194 
ESI (end-of-segment indicator)* 



establishing a priority 

for a job (PRTY) 30 

for a job step (DPRTY) 50 
evaluation rules* 
EVEN subparameter 36 
EXAMINE statement* 
EXCEPTION/ERROR 

additional information* 

for non-VSAM 148 

for VSAM 183-185 
EXEC statement 32-52 

accounting information (ACCT) 34 

bypass/execution conditions 
(COND) 35-37 

compiler options of PARM 
parameters 37-47 

definition 20 

dispatching priority (DPRTY) 50 

identifying 

procedure (PROC) 34 
program (PGM) 32-34 
step (stepname) 34 

keyword parameters 34-51 

linkage editing options of PARM 
parameter 47 

loader options of PARM parameter 47, 48 

PARM parameter 37-48 

passing information between programs 37 

reguesting restart (RD) 49 

setting time limit (TIME) 50 

specifying region size (REGION) 51 
execution, flow and rules* 
execution, steps in 18 
execution statistics 278 
execution time 

data sets 79-81 

definition 19 

job control checklist 514-518 

options 48-51 

output example 245, 461-471 

storage allocation 458-459 

with REGION parameter 457 
EXHIBIT statement 

additional information* 

and program debugging 251-253 

and required DD statement 80 
EXHIBIT subroutine 477 
exit from Declarative procedure* 
exit list codes 158 
exit point for procedures* 
EXIT PROGRAM statement* 
EXIT statement* 
EXPDT subparameter 66 
explicit information* 
exponent* 

exponentiation operator* 
EXTEND 142, * 

extended source program library* 
extending data sets 142 
external data concepts* 
external decimal items* 
external decimal subroutines 473-476 
external floating-point* 
external floating-point subroutine 474 
external references, COBOL subroutines 346 
external symbol dictionary (ESD) 240 
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F recording mode* 

fall through* 

false evaluation of IF* 

FCB parameter 68 

FD 

additional information* 
programming techniques 283 
relationship to DCB 491-495 
with WRITE ADVANCING 85 
FDECK option of lister 44, 212 
Federal Information Processing Standard 

level 40 
field count* 
figurative constant* 
file 

additional information* 
and COBOL clauses 84, 283-284 
and DD statement 82-83 
and SELECT sentence 82 
beginning address 62 
converting to VSAM 201-202 
definition 82 
initial loading (VSAM) 188 
member 83 
name 82 

processing techniques 83-131 
ASCII 

direct 83, 91-109 
indexed 83, 119-131 
partitioned 83 

physical (standard) sequential 83, 
relative 83, 110-118 
VSAM 180-184 
space allocation for 61, 59 
specifying information about a 83 
user defined 82-83 
VSAM (see VSAM files) 
FILE-CONTROL paragraph 

additional information* 
SELECT clause 82 
file description (OCR) 552 
File Description entry* 
file-name 

additional information* 
argument in calling program 322 
definition 82 
prefixes used with 283 
relationship with DD statement 82 
file positioning* 
file-processing 

additional information* 
non-VSAM 83-129 
VSAM 173-202 
File Section 

additional information* 
non-VSAM 283-284 
VSAM 185-186 
file space, determining 101 
FILE specification in VSAM 177 
FILE STATUS 

additional information* 
and IOB 154 
description 293 
for QSAM 146-148, 255-256 
for VSAM 

lists of keys 187-188, 192-193 
use urged 183 
FILLER* 



FINAL control* 

final results* 

FIPS level 40, * 

FIRST* 

fixed insertion editing* 

fixed-length item* 

fixed-length record format 160, * 

fixed-length table* 

fixed line size* 

fixed overlayable segments 378, * 

fixed permanent segment 378, * 

fixed portion* 

FLAGE/FLAGW compiler option 40 

floating insertion editing* 

floating-point items 

(see also computational fields) 
additional information* 
intermediate results 294 

floating-point subroutines 472, 475 

FLOW compiler option 41, 214 

flow of control* 

flow trace subroutine 482 

FOLD subparameter 60 

FOOTING 297, * 

FOR REMOVAL* 

format 

additional information* 
changing (see lister feature) 
record (see record formats) 

format of lister listing 210-211 
85-89 forms control image 68 

fragmentation of core, preventing 43 

FREESPACE parameter in VSAM 179 

fullword alignment* 

FUNC subparameter 88 

function- name* 



general registers, using to locate 

data 268 
GENERATE statement* 

generation data set (group) 141-142 
generic key* 
GETCORE subroutine 480 
GETMAIN usage and ENDJOB 43 
GIVING option 150-152, 368, .* 
global table 

description 236 

DMAP, PMAP options 39 

program 526-528 

task 519-526 
glossary (DMAP) 

definitions 239 

description 235-236 

requesting through EXEC statement 39 

symbols used 240 
GO TO statement 481, * 
GOBACK statement 

additional information* 

and assembler language 323 

and ENDJOB option 43 

greater than symbol* 
group entry* 
GROUP INDICATE clause* 
group item* 
group moves* 
group report* 
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halfword alignment* 

header labels 154-159, * 

HEADING* 

hierarchy 283, * 

HIGH-VALUE (HIGH-VALUES) figurative 

constant* 
HOLD macro for TCAK 434 
holding a job for later execution 31 
horizontal spacing* 
hyphen 25, * 

(see also minus symbol) 

1-0 CONTROL paragraph* 
1-0 files* 
1-0 options* 
I/O (see input/output) 

IBM-supplied cataloged procedures 356-363 
Identification Division 
additional information* 
reformatting 203-204 
identifier* 
identifiers in linkage argument 

list 316-326 
IEBUPDTE subroutine 348, 349 
IEFRDER DD card 438 
IF statement 295, * 
ILBO... subroutines 472-489 
ILBOABN0, user call to 254-255 
ILBOMCPN replacement 433 
ILB ONBLQ macro 43 4 
ILBOPRM and parameters 48 
ILBOSPIO and IMS calls 483 
ILBOSTP0, assembler-language call to 324 
ILBOSTT0 

calling from assembler language 323 
with ENDJOB option 43 
imperative statement* 
implicit items* 

IMS (see Information Management System) 
IN qualifier connective* 
IN subparameter 66 
INCLUDE statement 333, 338-339 
incomplete abnormal termination 277 
incrementing* 
indentation* 

independent overflow area 122 
independent segment 378, * 
index 

additional information* 
area 122 

cylinder 122, 121 
data item 305 

assigning values to 306-307 
master 128 
names 305, 306 

assigning values to 306 
overflow area 122 
prime area 122, 123 
quantity SPACE parameter 62 
track 121, 120 
index data item* 
index-name* 
INDEX usage* 

indexed access methods (see BIS AM, QISAM) 
INDEXED BY option* 

indexed data sets (see indexed files) 
indexed files 

(see also BISAM, QISAM, ESDS, KSDS) 
access techniques 127-131, 173 
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adding to 127-128 

additional information* 

APPLY clause 131 

calculating space requirements for 127 

cataloging 126 

creation and retrieving, in 
general 510-513 

creating of 123-126 

DD statements required 123-126, 201 

description 119-131, 173 

index area 122 

invalid key condition 148, 183 

master index 127 

overflow area 122-123 

prime area 122 

processing 119-131, 180-192 

random access 129-131 

READ statement 129 

RECORD KEY clause 119 

reorganizing 128 

REWRITE statement 129 

sequential access 127-129 

START statement 128 

updating 127-128 

VSAM 173-202 

WRITE statement 129 
indexed sequential access method, 

processing VSAM files 202 
indexed sequential data sets (see indexed 

files) 
indexes* 

indexing a table 305-306 
indexing* 

indicative dump, description 254 
indirect addressing 101 
Information Management System 

object-time debugging 483 

symbolic debugging 217 
informative messages (see messages) 
initial clause and state* 
initialization* 
INITIATE statement* 

inline procedures (optimization) 280 
input CD* 
input file* 
INPUT option* 
input phase of sort* 
input/output 

additional information* 

bypassing of 56 

error conditions 

completion codes for 257-259 

INVALID KEY 148 

standard error 143-147 

summary of 504-509 

USE AFTER ERROR declarative 148-154 

VSAM 184-188, 192-193 

facilities described in DD 
statement 51-69 

OCR 544-560 

subroutines 477-480 

VSAM 173-202 
input/output statements (see ACCEPT, CLOSE, 
DISPLAY, OPEN, READ, REWRITE, START, 
WRITE *) 
input phase of sort* 
INPUT PROCEDURE* 
input queue* 
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input stream 

control statements for 21, 56 

defining data in 56 

delimiter in 56 
INSERT statement* 
insertion editing* 
insertion symbol* 
INSPECT statement 477, * 
INSTALLATION paragraph* 
in-stream procedures 70 
instruction addressing causing 
interrupt 257-259 
integer* 

Interactive Debug 247, 213 
interface between COBOL and MCP 401, * 
intermediate control* 
intermediate results 294, 295, * 
internal data* 
internal decimal items* 
internal decimal subroutines 473-476 
internal floating-point* 
internal floating-point 

subroutines 473-476 
internal representation* 
inter-occurrence slack bytes* 
INTER-PROGRAM COMMUNICATION* 
interrupt address, examples 257-259 
INTO option* 

intra-record slack bytes* 
INTRO macro 433, 426 
invalid data 140, * 
INVALID KEY 

additional information* 

general 148, 508, 509 

in VSAM 183 
ISAM used to process VSAM files 202 



jamming (optimization) 270 
job 

accounting information 26, 20 

address space 32 

class assignment 31 

control statement display 27 

definition 18 

holding for later execution 31 

identifying 25 

library 353-354 

priority assignment 30 

reguest for restart 28-29 

setting time limits 30 

storage specification 31 

terminating 27 
Job Control Language 

character delimiters 24 

coding 22-25 

examples of 

compilation 514-515, 231-235 
linkage editing 240-241 

fields of 23-2* 

notation 25 

parameter for VSAM only 201 

statement continuation 24 

types of statements 

command statement 70, 20 
comment statement 71, 20 
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DD statement 51-69, 20 

delimiter statement 70, 20 

EXEC statement 32-52 

JOB statement 25-3 2, 20 

null statement 7 0, 20 

PROC statement 70, 20 
VSAM file processing 201 
job control procedures 20-81 
cataloged procedures 356-367 
checklist for 514-517 
Checkpoint/Restart 397-400 
definition 20 
libraries 347-349 
sort/merge 368-371 

for user files (see file, processing 
technigues) 
job management routines 22 
job schedulers 

description 22 

disposition messages from 241, 239 
in communications 436 
subroutine 479 
utility (CJS) 436, 480 
JOB statement 25-32, 20 

accounting information 26 
definition 25 
format 26 
parameters 

ADDRSPC 32 

CLASS 30 

COND 27 

MSGCLASS 31 

MSGLEVEL 27 

PRTY 30 

RD 28 

REGION 31 

RESTART 29 

TIME 30 

TYPRUN 31 
programmer identification 27 
job step 

bypassing 

using JOB statement 27 

using EXEC statement 35-37 
definition 18 
dispatching priority 50 
restarting 48-49 
JOBCAT DD statement 70 
JOBLIB DD statement 
description 69 
example of use 516-517 
restriction with cataloged 

procedures 357 
restriction with DDNAME 
parameter 366 
jobname 25 

joining data items* 

JUST* 

JUSTIFIED clause* 



KEEP subparameter 67 
KEY for a table* 
Key of reference* 
KEY option* 

(see also ACTUAL KEY clause and RECORD 
KEY clause) 
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key-sequenced VSAM data sets 

additional information* 

AIXBLD usage with 186 

defining 177-179 

examples 181-183, 194-198 

general 173 

reading 190 

writing 189 
key words* 

KEYS parameter in VSAM 179 
keyword parameter of control 

statements 23-24 
KSDS data sets (see key-sequenced VSAM 
data sets) 



L, invalid in CURRENCY SIGN* 

label handling subroutine 478 

LABEL parameter 65-67 

LABEL RECORDS clause* 

label specification* 

LABEL subparameter 66 

labels 

data set, relationship to SELECT and DD 
statements 144 

nonstandard 156-157 

routine return codes 159 

standard 155 

standard user 155 

user 155-158 

user totaling 156 

volume 154-156 

nonstandard 156 
standard 155 
LANGLVL option 

and ASCII 91 

and FIPS 40 

and segment re-initialization 379 

general 38 
language concepts and considerations* 
language name* 
language structure* 
LAST DETAIL* 
last printable line* 
last-used state* 
LC0L1 option of lister 44, 212 
LC0L2 option of lister 44, 212 
left padding, justification, and truncation* 
length of figurative constant* 
less than (<) character* 
LET loader option 48 
level indicator* 
level number 

additional information* 

normalized in glossary 236 
level- 01 items* 
level 02-49 items* 
level- 66 items* 
level-77 items* 
level-88 items* 
LIB compiler option 42 
library 

and BASIS card 351-352 

automatic call 78, 349 

changing 355 

COBOL copy 349-351 



COBOL subroutine 348, 472-489 

compilation, use of 73 

concatenating 79 

copy 349-351 

creating 354-355 

definition 83 

directory 347 

for PGM parameter 32, 34 

job 353 

JOBLIB statement 69 

link , 347-348, 76-73 

partitioned data set 83 

private 34, 6 9 

procedure 32, 35 

for program checkout 239 

relationship to JOBLIB DD 
statement 69, 78 

relationship to SYSLIB DD statement 76 

sharing 353 

sort 348 

source program 349-353 

STEPLIB statement 70 

subroutines 

arithmetic 476, 475 
COBOL 348, 472-489 
conversion 473-475 
input/output 477-480 
intermediate results 294-295 
sharing 353 

SYSLIB statement 76 

system 34, 76 

temporary 34 

user 349-353 
library management facility 353 
LIBRARY module* 
library-name* 
LIBRARY statement 333 
LINAGE 297, * 
line advancing* 
LINE clause* 
line continuation* 
line-control 216, * 
LINE-COONTER special register* 
line-number* 

LINECNT compiler option 39 
LINES AT BOTTOM/TOP 297, * 
link library 347-348, 76-78 
LINK macro to invoke compiler 499 
linkage conventions 316-326 
linkage, dynamic subprogram (see dynamic 

subprogram linkage) 
linkage editor 

additional input 332 

calling compiled programs 500 

capacity 502-503 

checklist 515 

data set reguirements 76-78 

definition 19 

external names 331 

input 

additional 332 
primary 332 

LIBRARY control statement 333 

messages 240, 242 

options 47 

output 240-242 

PAEM options 47 

primary input 332 
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processing 338-340 
user-specified data sets 76-78 
with libraries 353-355 
with preplanned overlay 340-341 
linkage registers 322 
Linkage Section* 
LINKLIB 76-78, 347-348 
LIST linkage editor option 47 
lister feature 203-212 
additional information* 
Data Division reformatting 2C4 
description 44 
Environment Division 

reformatting 204 
format conventions 210-211 
Identification Division 

reformatting 204 
operation of 203 
options 44-45, 212 
output deck 204, 211 
Procedure Division reformatting 207 
reformatting 204-207 
restrictions 203 
source listing 210 
specifying 212, 44 
summary listing 211 
type indicators 211 
literal* 

literal pool 237 
literal table 502 
literals, size considerations 502 
LOAD compiler option 39 
load list, example 267 
LOAD macro to invoke compiler 499 
load module 

additional information* 
as input to linkage editor 332 
definition 19 
length of 262 
output 243-245 

specification in EXEC statement 32 
loader 

cataloged procedure 360 

data set reguirements 78, 346 

definition 19, 346 

input 

additional 346 
primary 78 
reguirements 78 
invoking 360 
module map 244, 243 
output 243, 244 
PARM options 47-48 
RES restriction 346 
loading programs 

additional input 346 
cataloged procedure 360 
primary output 346 
locations in records* 
LOCK option* 
logical connectives* 
logical operators* 
logical page* 
logical record 

additional information* 
length 73, 496-497 
OUTLIM parameter 60 



logical record area 168, 169 
logical record length 73, 496-497 
logical record size 

for SYSIN 497 

for SYSLIB 497 

for SYSPEINT 497 

for SYSPUNCH 497 
LOW-VALUE (LOW-VALUES) figurative constant* 
lower-case letters in notation 25, * 
LRECL 73, 496-497 
LSTCOMP option of lister 44, 212 
LSTONLY option of lister 44, 212 
LTM subparameter 66 
LVL option of compiler 40 
L120 option of lister 45, 212 
L132 option of lister 45, 212 



machine considerations 4 57-460 
macro instructions 
ATTACH 499 
CALL 323-325 
CHKPT 395, 396 
DCB 490 
GETMAIN 43 
LINK 499 
LOAD 499 
magnetic tape 

additional information* 
data sets 

sharing devices, sort/merge 370 
using DEN and TRTCH 
subparameters 86-87 
devices 

compiler optimization using 496 
labels 154-159 

in sort/merge feature 36 8, 3 70 
volume 

private 63-64 
removable 64 
reserved 64 
scratch 64 
main line routines 292 
main program, definition 323, * 
main storage 

(see also storage allocation and storage 
considerations) 
REGION parameter 51, 31 
reguirements for Sort/Merge 373, * 
major control* 
map 

loader storage 243, 244 
memory 234 
module 244 
MAP option 

for linkage editor 47 
for loader 47 
mass storage 

device 99, 100 
space allocation 

SPACE parameter 61 
SPLIT parameter 62 
SUBALLOC parameter 62 
volume labels 154-156 
volume status 63-65 
volumes 63-65 
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mass storage files* 

master catalog (VSAM) 17 5-176 

maximum length 

additional information* 
in Data Division 283 
of blocks in COPY library 349 
maximum number 

additional information* 
of logical records (SYSOUT) 60 
maximum size (see maximum length) 
maximum value* 

MCP (see Message Control Program) 
member, definition 83 
MEMORY SIZE clause* 
merge (see sort/merge feature) 
merge subroutine 481 
message access* 
message code* 
message concepts* 
message control information* 
Message Control Program (MCP) 
activating 426, 455 
ANS reguirements 432-443 
building 

assembling 445 
executing 445 
link-editing 445 
communication with COBOL program 449-456 
data sets 427 

checkpoint data sets 445 
group data sets 446 
message gueue 446 
defining buffers 426 
defining interface 449 
defining process control blocks 455 
defining terminal area 427-429 
functions of 404 

interface with COBOL program 449-456 
JCL for 444 
macros 

CLOSE 426 
DCB 427 
INTRO 426 
INVLIST 428 
OPEN 426 
PCP 427 
READY 426 
RETURN 426 
TERMINAL 428 
TLIST 428 
TPROCESS 428 
TTABLE 428 
message flow 401-404 
message 537 
RECEIVE statement 297 
SEND statement 297 
user tasks 404-405 
writing a 404 
Message Control System* 
MESSAGE COUNT 479, * 
MESSAGE DATE* 
message delimiters* 
message indicators* % 
message handler (MCP). 426-432 
delimiter macros 429-430 
for application programs 431-432 
for terminal line groups 430 
functional macros 4 29-4 3D 



message gueues* 

message reception* 

message release and return* 

MESSAGE TIME* 

message transfer* 

message transmission* 

message unavailable* 

messages 

additional information* 

allocation 

compiler 235 
linkage editor 241 

checkpoint 396 

compile-time 569 

compiler, summary of 238-239 

disposition 

compiler 238 
linkage editor 241 

error 35 

ERRMSG 238-239 

execution-time (see object-time) 

identification codes 246 

linkage editor 240,242 

MCS considerations 537 

numbered on SYSTERM 37 

object-time 529-542 

operator 246,538 

gueue analyzer 539-542 

severity level of 
compiler 35 
linkage editor 35 

sort/merge 371 

unnumbered 538 

U-type 529 
Method B, to randomize 103 
method of data reference* 
minimun size* 
minimum value* 
minor control in a report* 
minus sign and symbol* 
mnemonic -name* 
MOD subparameter 67 

in Checkpoint/Restart 395 

in compilation 75 

definition 67 
MODE subparameter 87 
modular levels 292-293 
module map 244 
monitoring gueues 436 
MOVE statement 296,* 
MOVE subroutines 476 
MSGCLASS parameter 31 
MSGLEVEL parameter 

description 27 

with restart 397 
multidimensional table search* 
multiple checkpoints 394 
multiple file* 
MULTIPLE FILE TAPE clause* 
multiple indexing (VSAM) 173 
multiple libraries for COPY 349 
multiple redefinitions* 
multiple results* 
multiplication operator* 
MULTIPLY statement* 
multistep job 35-37 
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multivolume files 

additional information* 
direct 99-100 
volume switching 99 

MXIG subparameter 61 



name, definition* 

NAME compiler option 43 

name field 

of DD statement 56 

of job statement 23 
NAME statement 333 

name subparameter of DD statement 58 
names 

cataloged procedures 57 

data set, conventions used in 142 

generation 57 

procedure 502 

qualification of 57 

RENAMES clause 286 

temporary 58 
NATIVE collating sequence 293,* 
negated condition* 
negative data and sign* 
nested statements* 
"new" language (LANGLVL) 38,* 
NEW subparameter 67 
next executable statement* 
NEXT GROUP clause* 
NEXT options* 
NL subparameter 66 
NOADV option of compiler 44,160 
NOAIXBLD option 48 
NOBATCH option of compiler 42 
NOCALL option of loader 48 
NOCDECK option of lister 44,212 
NOCLIST option of compiler 39 
NOCOUNT option of compiler 44 
NOCSYNTAX option of compiler 41 
NO DATA option* 
NODEBUG option 48 
NODECK option of compiler 39 
NODMAP option of compiler 39 
NODUMP option of compiler 44 
NODYNAM option of compiter 43 
no end indicator* 
NOENDJOB option of compiler 43 
NOFDECK option of lister 44,212 
NOFLOW option of compiler 41,48 
NOLET option of loader 48 
NOLIB option of compiler 42 
NOLOAD option of compiler 39 
NOLVL option of compiler 40 
NOLST option of lister 44,212 
NOMAP option of loader 47 
NOMINAL KEY clause 129-130 
NONAME option of compiler 43 
noncontiguous items* 
nondeclarative reference* 
nonfooting body group* 
noninteger* 

nonnuraeric comparisons* 
nonnumeric item* 
nonnumeric literals* 
nonnumeric operands* 
nonreentrant subroutines 484-489 



nonreusable subroutines 484-489 

nonstandard labels 157 

nonswitched line* 

NONUM option of compiler 42 

nonunigue keys* 

non-VSAM file, converting to VSAM 202 

non-VSAM file processing (see user file 

processing) 
nonzero data* 

NOOPTIMIZE option of compiler 41 
NOPMAP option of compiler 39 
NOPRINT option 

of compiler 47 

of loader 48 
NOPWREAD subparameter 66 
NORES option of loader 48 
NORESIDENT option of compiler 43 
NO REWIND option* 

normalized level numbers in glossary 236 
NOSEO option of compiler 39 
NOSOURCE option of compiler 39 
NOSTATE option of compiler 40 
NOSUPMAP option of compiler 40 
NOSXREF option of compiler 42 
NOSYMDMP option of compiler 41 
NOSYNTAX option of compiler 41 
NOT* 

NOTE statement 296 
NOTERM option of compiler 47 
NOTEST option of compiler 47 
NOTRUNC option of compiler 40 
NOVBREF option of compiler 44 
NOVBSUM option of compiler 44 
NOVERB option of compiler 39 
NOXREF option of compiler 42 
NOZWB option of compiler 40 
NSL subparameter 66 
NUCLEUS module* 
null group* 
null statement 72 
NULLFILE DD parameter 58,74 
NUM compiler option 42 
NUMBERED specification in VSAM 179 
numerals* 
numeric category* 
numeric characters* 
numeric class* 
numeric comparisons 255, * 
numeric edited* 
numeric first character* 
numeric item* 
numeric literal* 
numeric operands* 



object code listing 237 
OBJECT-COMPUTER paragraph* 
object module 

contents 239-240 

deck 239 

definition 18 

dumps using 258-268 

listing 237 

size considerations 501-502 
Object Of OCCURS DEPENDING ON* 
Object Of REDEFINES * 
object of relation condition* 
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object program* 

object -time control cards (SYMDMP) 

continuation cards 215 

control statement placement 215 

example of 220-230 

line-control cards 216 

program-control cards 215 

syntax rules 215 
object-time options 

list of 48-49 

subroutine for 472 
object-time overlay 340-343 
object-time subroutine library 384,472-489 
occurrence number* 
OCCURS clause 

additional information* 

causing errors 255 

DEPENDING ON option 304-305 
OCCURS DEPENDING ON clause 

additional information* 

relationship to record formats 170-172 

table 502 
OCR (optical character reader) 
"old" language (LANGLVL) 38 
OLD subparameter 67 
OMITTED option* 
ON SIZE ERROR option 

binary items 291 

intermediate results 291 
ON statement 251, * 
ON OVERFLOW 295,317, * 
one* 

online printing* 
ONLY subparameter 36,37 
OPEN statement 

additional information* 

EXTEND 142,258 

for several files 296 

multiple use of 459 

VSAM files 185-188 
operand field 

bypassing I/O 56 

data definition 56 

on control statement 23 
operands* 
operating system environment 

Conversational Monitor System 19 

OS/VS1 19 

OS/VS2 19 
operation field 23 
operation order* 
operational sign* 
operator 

commands 7 

intervention* 

messages 246,529,538 
OPTCD subparameter 87 
optical character reader (OCR) 

additional information* 

COBOL capabilities 544 

COPY member 546-549 

document design 5ug 

exception handling 552 

file description 552 

format record assembly 553-554, 556 

I/O reguests 544 

implementing an application 549 

parameter data area 545 
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procedural code 552 

processing tapes from Model 2 560 

record description 552 

sample data 557 

sample document 555 

sample processing program 558-560 

sample program 553 

status key 545 

status key values 55C-551 
optical character reader interface 

subroutine 481 
optimization, compiler 496-498 
optimization methods 279-281 

backward movement 279 

common expression elimination 279 

efficiency guidelines 281 

inline procedures 280 

jamming 280 

reseguencing program 279 

SYMDMP output 279 

tabling 280 

unrolling 279 

unswitching 280 
OPTIMIZE compiler option 41, 237 
optimizing sort performance* 
optional clauses* 
optional entries* 
optional phrase* 

optional services (see OPTCD subparamet 
optional word * 
options 

error processing (VSAM) 183 

for compilation 38-47 

for execution 48 

for linkage editing 47 

for lister 44,212 

for loader 47-48 

PARM summary 46 
OR* 

order of* 

ORDER statement 334 
ordering records using sort/merge* 
ORGANIZATION clause* 
OS/VS COBOL* 
OS/VS1 

ADDRSPC parameter 32 

control program 19 

OUTLIM parameter 60 

SCAN action 31 

TERM parameter 60 
OS/VS2. 

ADDRSPC parameter 32 

control program 19 

DYNAM parameter 57 

intermediate data sets 458 

REGION parameter 458,21 

SCAN error 31 

TERM parameter 6C 

with TSO 57 
OUT subparameter 66 
OUTLIM parameter 60 
output 231-246 

compiler 231-239 

(see also compiler, output) 

copies of data set 60 

display of all compiler 
messages 238-239 

displaying control statements 27 
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ERRMSG program to display 
messages 238-239 

execution of load module 243-245 

linkage editor 240-242 

lister deck 204,211 

load module execution 243-245 

loader 243 

messages 

compiler 238-239 

linkage editor 242 

load module execution 243 

reformatted listing 44 

requesting various kinds 246 

return codes 35-37 

sample program 461-471 

stream data sets 134 

suppressing 496-497 

SYSOUT parameters 68 

system 246 
output CD* 

output deck, lister 204,211 
output device* 
output file* 
output listing format 

FCB parameter 6 8 

lister feature 44 

of compiler 231-239 
output mode* 
output option* 
output procedure* 
output record limit (SYSOUT) 60 
overflow area (see QISAM) 
overflow condition 

additional information* 

index 122 

synonym 108 
overlapping delimiters and operands* 
overlay 

dynamic 341-343 

preplanned 340-341 

statement 340-342 

structures 340 
overlayable segments* 
overriding DD statements 364-366 
OVFLOW 125 
OVLY linkage editor 47 



P in PICTURE and CURRENCY SIGN* 

packed decimal item* 

padding* 

page advancing* 

page areas* 

page body* 

page breaks 301-302, * 

page change in a 'report* 

PAGE clause* 

PAGE-COUNTER special register* 

page end* 

page fit test* 

PAGE-FOOTING* 

page format control* 

PAGE HEADING* 

page margins* 

PAGE option* 

page overflow* 

page placement* 



pagp positioning* 

gage size* 

PAGE statement 334 

paging 51 

paragraph* 

parameter data area (OCR) 545 

parameters 

compared to arguments 322,323 

key-word 23-24 

positional 23 

subparameters 23 

VSAM only (JCL) 201 
parentheses* 
PARM 48 
PARM option 

compiler options 38-47 

job card 48-49 

linkage editor options 47 

restrictions 37 

significant characters 37 

summary 46 

with equal sign 37 
partial key* 

partial list of prime numbers 10 5 
partial message* 
partitioned data sets 

description 83 

directory 333,61 

member 83 

primary quantity for 61,62 

secondary quantity for 61 

system library 34 

temporary libraries 34 
PASS subparameter 67 
PASSWORD clause* 
PASSWORD subparameter 66 
passwords in VSAM 181 
PATH command 175,178 
PATHENTRY specification in VSAM 179 
pathname as data set name 201 
PSS (see partitioned data set) 
PERFORM statement 296,378,* 
performed procedures* 
period* 

permanent segment 378,* 
permanently resident volumes 63-64 
permissible comparisons and options* 
PGM in EXEC statement 32,34 
PGT (see program global table) 
phrase, definition* 
physical page* 
physical record 61-62,* 
physical sequential file 

accessing 85-89 

additional information* 

data control block for 491 

data set 133 

DD statement parameters 123-126 

description 85-89 

error processing 143-154,508,87 

EXTEND 142 

locating data ares 268 

sort feature, uses 6 368 

subroutone for 479 

user label totaling 155 

with spanned records 274 
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PICTURE CLAUSE 

additional information* 

efficient use of 285-287 

storage allocation 287 
plural figurative constant* 
plus sign 287 r * 
PMAP compiler option 39 
POINTER* 

position in record* 
positive data* 
POSITIVE sign* 
prefixes 283 

preplanned linkage editor 340-341 
presentation rules, TYPE* 
PRESRES, member of SYS1.PSOCLIB 64 
preventing core fragmentation 43 
primary input, for called and calling 

programs 332,346 
primary keys, (VSAM) 173,189 
PRIME, in QISAM 122 
prime area (QISAM) 122 
prime number list 105 
prime record key* 
print files* 

print line size in report* 
PRINT option 

for compiler 47 

for loader 48 
print suppression* 

printer, determining line spacing 85 
printer channel control* 
printer character set 60 
printer device, SEND* 
printer spacing* 
priority, assinging 

for a job 30 

for a job step 50 
priority numbers 378,* 
priority schedulers 22 
priority scheduling system 

EXEC statement parameters 50 

JOB statement parameters 30 

sharing data sets 67 

SYSOUT parameter for 68 
PRIVATE subparameter 65 
private volume 64 

problems with compiler, resolving 543 
PROC statement 70 
procedure* 

procedure branching statement* 
Procedure Division 

additional information* 

intermediate results 293,294 

modular levels 292 

programming technigues 292-299 

reformatting 207-20 8 

report writer considerations 299-304 

state, emts (see compiler directing 
statements, conditional statements, 
imperative statements) 

string manipulation considerations 29 8- 

table handling considerations 304-3 09 

teleprocessing condiderations 309-315 

verbs 295-298 
procedure library 34,348 
procedure- name,* 
procedure-name table 502 
procedures, in- stream 70 



process definition* 
processing of files* 
processing program 18 
processing rules* 
processing subroutines 292 
procstep.ddname 56 
procstep subparameter 63 
program 

(see also programming technigues) 

called 317-318,325 

calling 317-325 

checkout 247-278 

collating seguences 293 

COUNT option 247,278 

debugging 247 

(see also symbolic debugging; 
lister feature) 
completion code 257-259 
dumps 254-257,260-263 
errors 

I/O 258 

invalid data 255-256 
other 256-257 
examples 262-273 
execution statistics 278 
I/O errors 258 

incomplete abnormal termination 277 
interruption, finding location 

of 259 
invalid data errors 255-256 
language 247 
other errors 256-257 
execution 

from private library 34 
from system library 34 
from temporary library 34 
multistep job 35-37 
interrupt 259 
linkage editor 338-340 
reseguencing 279 
sample 461-471 

selective testing of 217-219,253-254 
technigues (see programming technigues) 
PROGRAM COLLATING SEQUENCE (see collating 

seguence) 
program- control cards 215 
program global table (PGT) 237,527-528 
PROGRAM-ID 213,* 
program-name* 
program relationships* 
program segments* 
program structure* 
program switch* 
program syntax* 
program termination* 
programmer identification 27 
programming notes* 
programming techigues 28 2-315 
(see also program) 
Data Division 282-315 
299 Environment Division 282-283 
general 282 

optimization methods 278-281 
Procedure Division 29 2-299 
gueue structure considerations 309-315 
report writer 299-304 
sort feature 372-373 
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table handling 304-309 

VSAM 180-193 
PETSP subparameter 87 
PRTY parameter 30 
pseudo data set 56 
pseudo-text* 
public volume 64 
punch device* 
punch files* 
punctuation character* 
punctuation rules 



Q routines 472 
QISAM 

(see slao BISAM, indexed files) 

considerations when using 128-131 

data control block 128 

data sets 134 

creating 123-125 
definition 82 
deleting records in 129 
reorganizing 129-130 

DD statement parameters 128-129 

error processing for 143-147 , 508 

indexes, description 122-123 

master index 127 

overflow area, description 122 , 123 

prime area, description 122 

single volume file 125-126 
QNAME parameter 58 
QSAM 

data control block 491 

data set 133 

DD statement parameters 123-126 

description 85-89 

error processing for 143-154,508,87 

extending 142 

locating data areas 268 

sort feature, uses of 368 

subroutine for 479 

user label totaling 

with spanned records 
gualif ication* 
gualified data name* 
qualifiers* 
queue access* 
Queue Analyzer Routine 
queue blocks 

and locating TCAM data areas 27 5-276 

sample program 275 
gueue concepts* 

QUEUE DEPTH field and IF statement 280 
queue messages* 
queue name 449, * 
QUEUE object-time option 49,438 
queue relationships* 
queue structure 

accessing with COBOL 312-315 

additional information* 

example 310,311 

Queue Structure Description routine 315 

SCAN subroutine 479 

SYMBOLIC QUEUE name 309 
quotation mark 40,* 
QUOTE compiler option 40 

QUOTE (QUOTES) figurative constant 40,* 
quotient* 



155 
274 



309-315 



R, in currency sign* 

random access* 

randomizing techniques 101-103 

range of procedures, PERFORM* 

ranges of value* 

RD Entry* 

RD parameter 

for a job 28 

for a job step 49 

with checkpoint 396-397 

with deferred checkpoint 69 
READ INTO option 296 
READ statement 

additional information* 

in BISAM 130 

in QISAM 127-130 

in VSAM 189-190 
READY TRACE statement 251,39,* 
RECEIVE statement 297,* 
receiving device* 
receiving item* 
receiving field* 
RECFM subparameter 

in compilation 497 

in DISPLAY statement 79-80 
record 

additional information* 

addressing 83 

blocked 80 

capacity 93 

dummy 93 

duplicate 504 

formats 84 

fixed-length 160 
spanned 164-165 
unspecified 161 
variable-length 161-164 

segments 165-166 

size, logical 

for SYSIN 497 
for SYSLIB 497 
for SYSPRINT 497 
for SYSPUNCH 497 

size restriction, physical 61 

sort/merge fields 372 
record area* 
record availability* 
RECORD CONTAINS clause 284,* 
record discription (OCR) 552 
record discription entry 

in BISAM 129-130 

in QISAM 129 
record formats 160-172 

effect of OCCURS clause 170-172 

fixed length 16C 

spanned 164-170 

unspecified 161 

variable length 161-164 
RECORD KEY* 
record level* 
record-name* 
record seguencing* 
record size* 
recording mode* 
records in error* 
RECORDS option* 
REDEFINES clause 285-286,* 
REEL options* 
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reentrant subroutines, list of 484-489 

JEF subparameter 65 

[reference frequency* 

reference summary* 

[referencing tables 304 

REGION parameter 

ADDRSPC parameter 51,31 

for OS/VS2 21,458 

in EXEC statement 51 

in JOB statement 31 

main storage 31 

used in compilation 458 

used in execution 458 
register assignment, location in 
output 237 
reinitialization* 

DELATE specification for VSAM 178 
relation character* 
relation condition* 
relational- operator* 
relative files 

accessing 112 

additional information* 

allocating space for 112 

COBOL clause for 118 

creating 111-112 

error processing 143-154 

Job Control Language for 120 

NOMINAL KEY, use of 110,111 

processing 110-117 

random access 112-113 

sample program 114-117 

sequential access 112 

VSAM 174 
relative indexing* 
relative indexing* 
RELATIVE key* 
relative line* 
relative NEXT GRoup* 
relative organization* 
relative record data sets (VSAM) 

defining 179 

described 174 

reading 181,190 

writing 189 
relative record number* 
tELEASE statement in sort* 
releasing a job (RELEASE) 31 
relocation list dictionary (RLD) 503 
reminder* 
IEMARK papagraph* 
remote station* 
removable volumes 63,64 
REMOVAL option* 
removing file records* 
RENAMES clause 286,* 
repetition of item* 
repetitive execution* 
replacement editing* 
replacement of file records* 
replacement rules for library-text* 
tEPLACING option* 
report calculations* 
REPORT clause* 
report description (RD) * 
report file* 
REPORT FOOTING* 
teport Group 299-300,* 



REPORT HEADING* 
report-line* 
report-name* 
report page depth* 
report printing online* 
report processing* 
Report Section* 
report, writer 

additional information* 

CODE clause 302 

Data Division considerations 

floating first detail 303-304 
output footings 303 
output line overlay 301 

Procedure Division considerations 299-304 
size considerations 303,304 
SUM 300-301 
tables 502 
reports, decribing* 
reguesting a message class 31 
reguesting a unit 58-59 
required clauses, entries, items, words* 
RERUN clause 

additional information* 

and JCL 49-50 

and RD parameter 394,396 
RES loader option 48 

resequencing program (optimization) 279 
RESERVE clause 85,* 
reserved volumes 64 
reserved words* 
RESET option of sum* 
RESET TRACE statement 251 
RESIDENT 

example 337 

linkage 335 

specifying 335,336 
RESIDENT compiler option 43 
resolving compiler problems 54 3 
Restart 

(see also Checkpoint/Restart) 

automatic 397 

checkpoint 394 

(see also Checkpoint) 

deferred 397-398 

for cataloged procedure 48-49 

in a job 28-29 

in a job step 48-49 

initiating 394 

RD parameter 396-397 

system routine 396 
RESTART parameter (see RD parameter) 
restarting a program* 
restrictions* 
result field* 
RETAIN subparameter 65 
RETPD subparameter 66 
retrieving data sets 

cataloged 138 

example of 140 

noncatloged 139 

passed 139 

through an input stream 139-140 

VSAM 195-198 

with additional output 139 
return code 35,158,* 

RETURN-CODE special register 317,322,* 
return mechanism (sort/merae) * 



"Consult VS COBOL for OS/VS (GC26-3857) 



Index 583 



return of control* 

return register 322 

RETURN statement for sort/merge* 

reusable subroutines, list of 484-489 

reusable VSAM data sets 179 

REUSE parameter in VSAM 179 

rewinding of tape files* 

REWRITE statement 

additional information* 

in BISAM 130 

in QISAM 128 

in VSAM 189 
rightmost sign specification* 
right-padding* 
right parenthesis* 

RLD (see relocation list dictionary) 
RLSE subparameter 61 
ROUND subparameter 61 
ROUNDED option* 
routine-name* 

RRDS (see relative record data sets) 
RT subparameter 60 
rules* 
run unit 32 3,* 



S, PICTURE clause symbol* 
S-mode records 164-165,* 
SAME clause* 

sample program output 461-471 
save area layout 332 
scaling 286,* 
SCAN with HOLD 31 
schedulers 

job 22 

master 22 

priority 22 
SD entry* 
SEARCH statement 

additional information* 

subroutine for 481 

use of 307-309 
searching a table 307-308 
secondary guantity subparameter 

for SPACE 61 

for SPLIT 62 
section* 
section header* 
section- name* 
SECURITY paragraph* 
SEGMENT-LIMIT clause* 
segment of a message* 
SEGMENT option* 

segment work area 165,169-170 
segmentation 

additional inf6rmation* 

and PERFORM statement 378 

effect of LANGLVL 379 

output 379-393 

program organization 378 

subroutine 481 
SELECT clause 

additional information* 

relationship to DD statement 14 4 

with user files 82 
SELECT OPTION clause* 
SELECT OPTIONAL statement 56 



selective summation* 

SEND statement 297,* 

sending field* 

sentence* 

SEP parameter 58 

SEPARATE option of SIGN 

clause 288,* 
separate programs* 
separate sign* 
separator* 

SEQ compiler option 39 
sequence* 

sequencing records using sort/merge* 
sequential access* 
sequential data sets 

DUMMY parameter 56 

for VSAM 173,180 

on mass storage devices 133 
sequential files* 
sequential single volume files* 
SER subparameter 65 
serial search of a table 308,* 
series connectives* 
SET statement 305-306,* 
SETEOF macro 455 
setting time limits 

on a job 30 

on a job step 50 
severity levels 35, 238 
sharing 

data sets 67 

COBOL library subroutines 353 
sharing storage* 
SHR subparameter 67 
sign, efficient use of 287-288 
sign character* 
SIGN clause 287-288,* 
sign condition* 
sign control* 
sign in numeric literal* 
SIGN IS SEPARATE* 
signed numeric* 
significance order* 
simple condition* 
simple insertion editing* 
single checkpoint 384 
single entry report group* 
single IF* 
single message* 
single quotation mark* 
single-segment message 297 
single-statement paragraph* 
single values* 

singular figurative constant* 
SIZE ERROR option 255,* 
size of operands* 
SIZE option 

for compiler 38 

for loader 48 
SIZE, STRING delimiter* 
SL subparameter 89, 90 
slack bytes* 
slash (/) 48,* 

SORT-CORE-SIZE special register 373,* 
sort debug subroutine 481 
sort file* 

SORT-FILE-SIZE special register 373, * 
sort library 371, 348 
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sort/merge debug feature 377 
Sort/Merge Feature 368-376 

additional information* 

alternate collating sequence 293,375 

and Checkpoint/Restart feature 372 

ASCII considerations 37 5 

cataloging 371 

collating sequence 37 5 

completion codes 371 

considerations 460 

Data Division considerations 374 

data set size 373 

DD statements 368-371 

for ASCII files 375 

linkage with SORT/MERGE 373 

main storage registers 373 

main storage requirements 373 

messages 373-374 

program example 370 

record fields 372 

sample program 370 

sharing devices 370 

SPACE parameter 369 

storage allocation 373 

subrouting 480 

terminating 371 

variable length records 374,376 

with Checkpoint/Restart 372 

with spanned records 368 
Sort-Merge File Description (SD)* 
SORT MESSAGE special register* 
SORT-MODE-SIZE special register* 
SORT-RETURN special register 371-372,* 
SORT statement* 
sort subroutine 348,480 
sort work-file 368,* 
SORTCDS DD card 377 
sorted records* 

sorting variable-length records 374, 376 
SORTLIB DD statement 370 
SORTWKnn DD statement 368-369 
SOURCE clause* 
SOURCE compiler option 39 
SOURCE-COMPUTER paragraph* 
source/destination and MCS* 
source item* 

source listing by lister 210-211 
source module 215,18 
source program 501-503,* 
source program library 349-350 

(see also COBOL copy library) 
source program library feature* 
SOURCE-SUM correlation 300 
space* 

SPACE (SPACES) figurative constant* 
SPACE parameter 61-62 

in BSAM 88,89 

in creating data sets 132-134 

in QISAM 124 

in sort feature 369 

SPACEn option 40 

subparameters 61-62 
SPACE subparameter 61-62 
SPACEn compiler option 40 
spaces* 
spacing* 



spanned records 164-170 

blocked 164-165 

description 164-165 

direct processing 169-170 

formatting 164-165 

locating in dumps 274-275 

logical record area 166 

segment work area 164 

sequential processing 164-165 

specification 164,168-169 

with sort 368 
special character* 
special characters in job control 

language 25 
special collating sequences* 
special features* 
special insertion editing* 
special level-number concepts* 
SPECIAL- NAMES paragraph* 
special registers 

additional* 

DEBUG-ITEM 248 

for date and time 481 

RETURN-CODE 317, 322 

SORT-CORE-SIZE 373 

SORT-RETURN 371-372 

time and date 481 
special situations, STOP useful for* 
specification order* 
specifying address space parameter 

description 32 

with REGION parameter 31 
specifying data set status and 

disposition 67-68 
specifying loader input 78 
SPIE subroutine 483 
SPLIT parameter 

description 62 

in creating data sets 132-134 

in QISAM 124 
SPLIT subparameters 62 
square brackets in formats 2 5,* 
STACK subparameter 87 

stacked items, in job control notation 25 
standard alignment rules* 
standard COBOL format* 
standard data format* 
standard labels 155-156,* 
STANDARD option* 

standard selection (LANGLVL) 38 
standard sequential file (see physical 

sequential file) 
standard system I/O error routine* 
standard user labels 155-156 
STANDARD-1 collating sequence 293,* 
START statement 298,* 
START verb (VSAM) 183 
STATE compiler option 40 

subroutines 482 
statement* 

statement number subroutine 482 
static CALL statement 318,* 
static values of a table* 
statistics in output 237 
Status Key (OCR) 545,550-551 
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Status Key (QSAM and VSAM) 
additional information* 
QSAM 255-256,87,148 
VSAM 183,184-188,192-193 
step restart 
in a job 29 
in a job step 48-49 
STEPCAT DD statement 70 
STEPLIB DD statement 69 
stepname 34,63 

steps to resolve compiler problems 
STOP RUN initialization subroutine 
STOP RUN messages subroutine 472 
STOP RUN statement 

additional information* 
and assembler language program 
and ENDJOB option 43 
STOP RUN termination subroutine 472 
STOP statement* 
storage allocation 

(see also main storage and storage 
considerations) 
additional information* 
for compilation 73,501 
for execution, job step 51 
for linkage editing 502-503 
for overlay processing 340-345 
for sort feature 373 
for source program 501-502 
storage considerations 501-502 

(see also main storage and storage 
allocation) 
storage format, USAGE* 
storage layout of table* 
storage map, for loader 244,243 
storage, mass (see mass storage) 
storage of records* 
storage sharing* 
storage volume 63-65 
STRING statement 297,* 
structure of COBOL* 
sub-gueue structures 309-315,* 
SUBALLOC parameter 62 
SUBALLOC subparameter 
description 62-63 
in creating data sets 132 
subdivisions of page* 
subfield contents of DEBUG-ITEM 
subject* 

subordinate entries* 
subordinate report group* 
subparameters 23 
subprogram 

additional information* 
and CANCEL statement 335 
and dynamic CALL 317,318 
and static CALL 318 
subprogram linkage feature* 
subroutine library (see library) 
subroutines 

(see also library) 
arithmetic 475-476 
conversion 473-475 
data management 477-480 
data manipulation 476-477 
external references 346 
for linkage 472 
for special features 483 
input/output 477-480 



543 
472 



323-325 



249, : 



subscript* 

subscript redefinition 286 

subscriped data name* 

subscriping* 

substitution field* 

SUBTRACT statement* 

subtraction operator* 

SUL subparameter 66 

SUM clause* 

SUM counter* 

SUM statement 300-301 

summary listing by lister 209,211 

summary reporting* 

summation* 

superscript in job control notation 25 

SUPMAP compiler option 40 

SUPPRESS option* 

suppression of report groups* 

suppression of seguence checking* 

suspension of execution* 

switches (see UPSI switches) 

switch-status condition* 

switched line* 

SXREF compiler option 42 

symbol orer, PICTURE* 

symbolic debugging 213-230 

flow trace option 213-214 

(see also FLOW compiler option) 

interactive debug option 213 

(see also TEST compiler option) 

run unit considerations 216 

statement nember option 213 

(see also STATE compiler option) 

symbolic debug option 214-216 

(see also SYMDMP compiler option) 
object-time control cards 215-216 
sample program 217-230 
TSO considerations 214 
type codes 218 

under Information Management System 
(IMS) 217 
symbolic destinations 435,* 
symbolic dump subroutine 482 
SYMBOLIC QUEUE 

accessing gueue structures 312-313 

additional information* 

Q Analyzer routine 309-315 
SYMBOLIC SOURCE* 

SYMBOLIC SUB-QUEUE 309,311-312,* 
symbols used in PICTURE clause* 
SYMDMP compiler option 41 

(see also symbolic debugging) 

abnormal termination dump 214 

abnormal termination message 214 

and data-names 214 

Data Division dump 214 

general considerations 216 

object-time control cards 215-216 

operation of 214 

sample program 217-230 

specifying through PARM 
parameter 214-215 

subroutines 482 

type codes 218 
SYMDMP error message subroutine if 82 
SYNCHRONIZED clause* 
synonym overflow 108 
syntax-checking compilation 247 
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SYNTAX compiler option 41 

syntax of program* 

SYSABEND DD statement 69,80-8 1, 246 

SYSCHK DD statement 69,398 

SYSCJS DD statement 4 37 

SYSCOUNT DD statement 81 

SYSCP 21 

SYSDA 21 

SYSDBG data set 

default for 216 

requirement for 246 

use of 215 
SYSDBOUT DD card 213,246 

for COUNT option 81 

system logical input unit* 
SYSDTERM DD card 214,246 
SYSIN DD statement 

concatenating with SYSLIN 367 

for compilation 74 

in cataloged procedures 359-363 

logical record size for 497 

relationship to ACCEPT statement 8C 
SYSIN-SYSOOT 458 
SYSLIB DD statement 

for compilation 76 

for copy 349 

for linkage editing 78 

for loading 78 

logical record size for 497 
SYSLIN DD statement 

concatenating with SYSIN 367 

for compilation 75 

for linkage editing 76 

for loading 78 

logical record size for 497 
SYSLMOD DD statement 

for linkage editing 77-78 

with job library 353 
SYSLOUT DD statement for loading 79 
SYSOUT system logical output unit* 
SYSOUT parameter 68 

and COPIES parameter 60 

effect of SYST option 43 

in sort feature 370 

relationship to DISPLAY statement 79-80 

subparameters 68 

use of 68 
SYSOUT subparameters 68 
SYSPRINT DD statement 

for compiler 74 

for linkage editor 76 

for VSAM 186 

loqical record size for 497 
SYSPUNCH definition* 
SYSPUNCH DD statement 

for compiler 74 

logical record size for 497 

relationship to DISPLAY statement 79-80 
SYSSQ 21,59 

SYST compiler option 43 
system catalog, creating 18 
system considerations , subprogram linking* 
system console* 
system dependencies* 
system diagnostic messages 246 
system error recovery 143-149,* 
system-generated code* 
system independent binary items* 



system information 
system input device 
system logical outp 
system-name (assign 
system output messa 
system parameter li 
system restart rout 
System/370 unit rec 
SYSTERM DD statemen 
SYSUDUMP DD stateme 
SYSUT1 

blocksize 496 
for compilation 
for linkage edit 
SYSUT2 73,496 
SYSUT3 73,496 
SYSUT4 73,496 
SYSUT5 

blocksize 498 
for compilatiion 
required by SYMD 
SYSUT6 

blocksize 498 
for compilation 
required by LVL 
SYS1.COBLIB 348 
SYS1.LINKLIB 348 
SYS1.PROCLIB 

adding procedure 
description 348 
SYS1 .SORTLIB 

description 348 
storage allocati 
SYS1.TELCMLIB 447 
S01 and S02 functio 



transfer,- ACCEPT* 
* 

ut device* 

ment-name) 90,100,* 

ges 246 

brary 64 

ine 396 

ord processing* 

t 7 4,77 

nt 69,246 



73 

ing 78 



73 
MP and TEST 41,217 



73 

40 



s to 356-357 



,370 

on for 373 



n-names* 



table elements 304-309,* 

table handling 304-309,* 

table layout* 

table of moves* 

table references* 

table values* 

tables 

building 309 

handling considerations 304-308 

storage limitations 501-502 

subscripts 304 
tabling (optimization) 280 
TALLY special register* 
TALLYING option* 
tape (see magnetic tape) 
tape file* 

tape volume state 64 
tapes from 3886 OCR 560 
task global table 236-237 

fields of 527 

use to locate data-names 268 

using SYMDMP to examine 214 
TCAM (telecommunications access method) 

data areas 275-276 

locating 275-276 

gueue blocks 276 

RECEIVE statement 276 

SEND statement 276 

service facilities 456 

writing compatible programs 446 
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TCLOSE facility 74 

teleprocessing (communications feature) 

(see also MCP, message control program) 

and CD entries 284 

and Communication Section 284 

and MCP 401,404 

ANS standard requirements 432 

environment 401 

sample MCP 406-425 
temporary data set 

creating 135 

description 63 
temporary library 34 
temporary names 58 
TERM compiler option 47 

effect of LVL option 40 
TERM parameter 60 
terminal device, SEND* 
terminal error messages 35-36 
TERMINAL option* 
terminal table 433-436 
TERMINATE statement* 
terminating file processing* 
termination of execution* 
termination of job 27 
TEST compiler option 47,213 

requires SYSUT5 73 
TESTRUN sample program 461-471 
TEXT LENGTH* 
text name* 

text punch table 501 
text word* 

TGT (see task global taale) 
three-dimensional table* 
three operands, varying* 
TIME-OF-DAY special register 481,* 
TIME parameter 

for a job 30 

for a job step 50 
TIME special register 481,* 
TIMES option of PERFORM* 
TO options* 
top page margin* 
totaling, user label 155 
TPROCESS entries 432 
trace option 88 
TRACE statement 

description 251-252 

relationship to SYSOUT DD statement 8 
TRACE subroutine 482 
track 

addressing 83,91 

capacity 101,102,103 

identifier 91 

index 120-122 

space for 94,95 
TRACK-LIMIT clause 94,95 
trailer labels 159,* 
TRAILING option* 
transfer of control* 
transfer of data* 
TRANSFORM statement 298,* 
TRANSFORM subroutine 477 
transformation rules* 
transmission to messages by SEND* 
TRK subparameter 61 
TRTCH subparameter 87 
true condition* 



TRUNC compiler option 40 

truncation of data* 

truth value* 

TS subparameter 60 

two-dimensional table* 

two operands, varying* 

twos complement form* 

TYPE clause* 

type indicators for lister 211 

TYPRUN parameter 31 



U-type abend 529,254 
UCS parameter 60 
unary operator* 
unblocked files* 
unblocked records 

fixed-length 160-161 

permissible file techniques 84 

spanned 164-165 

variable-length 161-163 
unblocking, automatic* 
UNCATLG subparameter 68 
unconditional GO TO* 

unconditional syntax-checking compilation 41 
undefined length records (see unspecified 

length records) 
unequal fields 286-287 
unequal size operands in nonnumeric 

comparisons* 
unique table references* 
ONIQUEKEY specification (VSAM) 179 
unit, requesting 58 
UNIT option* 
UNIT parameter 

creating data sets with 131 

description 58 

multivolume data sets using 99-100 

retrieving data sets with 139 

sort programs using 369 

subparameters 59 
unit record data set 133 
unit record device, DD statement for 141 
unit record file* 
UNIT subparameters 59 
unloaded files (VSAM) 185 
unrolling (optimization) 279 
unsigned data, USAGE* 
unsigned integer, stop* 
unsigned numeric literal* 
unsigned operand* 

unspecified length records, format 161 
unspecified record format (see U-mode 

records) 
UNSTRING statement 299,* 
unswitching (optimization) 280 
UNTIL option* 

UPDATE specification in VSAM 179 
updating files* 

UPGRADE specification in VSAM 179 
upon options* 
upper-case letters, in job control 

notation 25 
UPSI switches 293,48,* ! 
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USAGE clause 

additional information* 
causing errors 255 
efficient use of 288-290 
example 236 
USE AFTER ERROR option 

description 148-149,183-184 
in file processing techniques 491-494 
USE BEFORE REPORTING* 
USE FOR DEBUGGING 

additional information* 
controlled by DEBUG option 48 
effect on SYMDMP option 41 
effect on TEST option 47 
example 250 
general 248-249 
subroutine for 482 
USE PROCEDURES* 

USE statement (see declaratives) 
user abends 529,254,44 
user catalog (VSAM) 176 
user completion code 529,254, 44 
user-defined files 82 
user-defined word* 
user file processing 

non-VSAM files 82-159 
ASCII files 89-90 
data set organization 83 
direct file processing 91 
error processing 143-154 
indexed sequential 119-130 
label processing 154-159 
names 82 

physical sequential 85-89 
processing techniques 83-130 
relative file processing 110-118 
standard (physical) sequential 85-89 
VSAM files 173-202 

access method services 174-180,186 
COBOL language usage 193-201 
converting non-VSAM files 201-202 
current record pointer 181 
error handling 183-184 
features unavailable 202 
initial loading of records 188 
ISAM programs with 201-202 
JCL for 201 
password usage 181 
programming consideration 180-191 
status key values 183 

for action requests 192-193 
for OPEN requests 184-188 
types of data sets 173-174 
warning 183 
user-initiated dumps 254 
user label procedure 156-157 
user labels 155-159 
(see also labels) 
and ASCII files 158-159 
exit list codes 158 
exits 158 
return codes 158 
totaling 156 
I user libraries 349-354,69 

user parameters for execution 48 
User Program Status Indicator 
(see UPSI switches) 



user-specified collating sequences 

(see collating sequence) 
user-specified data sets 78-79 
USING option 

for execution parameters 48,* 
in sort/merge 368,* 
utility dats sets 

and job control procedures 21 

for compilation 73,75 

for linkage editing 78,77 
utility programs 

IEBUPDTE 348,349 

IEHLIST 278 

IEHMOVE 347 

IEHPROGM 277 
utility subroutines for communications 

ILBDCJS 436-438,480 

ILBOQSU 479,487 



V, in CURRENCY sign and PICTURE clause* 
V recording mode* 

valid and invalid elementary moves* 
valid execution sequence, PERFORM* 
validity checking* 
VALUE clause* 
VALUE OF clause* 
value of numers literal* 
value range of conditional GO TO* 
variable-length item* 

variable-length record size specification* 
variable-length records 
additional information* 
and OCCURS DEPENDING ON 170-172 
description 161 

format 161-164 
variable-length table* 
variable line lengths* 
variable page spacing* 
variable record sizes* 
varying operands and options* 
VBREF compiler option 44 
VBSUM compiler option 44 
verb* 

VERB compiler option 39,237 
verb cross-reference 44 
verb summary 44 
verb usage (count) 44 
verbs, techniques with 295-299 
VERIFY 

FCB 59 

implicit in VSAM 184 

UCS 60 
vertical page positioning* 
vertical spacing* 
virtual storage access method (see VSAM 

and user file processing) 
volume 

definition 18 

labels 154-159 
ASCII 159 
nonstandard 157 
standard 155-156 

magnetic tape 64 

mass storage 63,64 

nonspecific 63 
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prameter (see VOLUME parameter) 

permanently resident 63 

private 64 

public 64 

reference 64 

removable 64 

reserved 64 

specific 63 

state 64 

storage 64 
volume, switching 99 
volume-count subparameter 65 
volume lables* 
VOLUME parameter 63-65 

creating data sets with 133 

description 63-64 

retrieving data sets with 139 

subparameters 65 

with UNIT parameter 59 
volume removal* 

volume-sequence-number subparameter 65 
volume switch* 
VSAM (virtual storage access method) files 

additional information* 

AFF subparameter 59 

AMP parameter 69 

DEFER subparameter 59 

DUMMY parameter 56 

features not available 202 

file processing (see user file 
processing) 

JOBCAT statement 70 

SEP subparameter ^9 

SHR subparameter 68 

STEPCAT statement 70 

user catalog 70 

warning about 183 
VSAM subroutines 479 



separate modules 285 

WRITE FROM option 296 
WRITE ADVANCING 297,* 
WRITE AFTER ADVANCING option 
• additional information* 

ADV option 44 

restriction with PRTSP parameter 87 

use of 85 
WRITE AFTER POSITIONING option 

restriction with PRTSP parameter 87 

use of 85 
WRITE FROM option 296 
WRITE statement 

additional information* 

causing errors with 257 

in VSAM 193-195 



X, in CURRENCY SIGN and PICTURE clause* 
XREF option 

for compilation 42 

for linkage editing 47 



Z, in CURRENCY SIGN and PICTURE clauses* 

zero* 

ZERO (ZEROES, ZEROS) figurative constant* 

zero filling* 

ZERO sign test rules* 

zero suppression* 

zero value* 

zoned decimal item* 

ZWB compiler option 40 



W (warning severity level 238,35 

wait state time limit 21 

wait status* 

wait subroutine 478 

warning 

used as a severity level 

(W) 35,238 

using status key with VSAM 183 
WHEN-COMPILED special, register* 
WHEN option of SEARCH ALL* 
WITH DEBUGGING MODE 

additional information* 
controlled by DEBUG option 48 
effect on SYMDMP 41 
effect on TEST 47 
general 248-249 
with footing* 
with NO REWIND* 
with phrase of SEND* 
word 62,* 

workfile under VSAM 179 
Working-Storage Section 

additional information* 

finding in dump 285 

location and length, determining 237 

READ INTO option 296 
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